Purpose

This document will serve as a high-level guide for the overall procedure for renewal / replacement of SSL certificates in FID server

Scope

This document mostly summarizes information from the System Administration Guide under the title. "Replacing the Default Self-Signed Certificate"., with additional context given. Although it says "Replacing your default Self-Signed Certificate" the steps are exactly the same for renewal too. It is recommended to read this supporting documentation.

Definitions

Keystore:

• A file present under RLI_HOME/vds_server/jetty/conf folder which is named as rli.keystore by default. The default password is 'radiantlogic' , it is recommended that this is kept the same for troubleshooting simplicity
• A Java KeyStore (JKS) is a repository of security certificates – either authorization certificates or public key certificates – plus corresponding private keys, used for instance in TLS/SSL encryption.
• JKS is a format specific to Java, while PKCS12 is a newer ,standardized and language-neutral way of storing encrypted private keys and certificates. (The PKCS12 keystore file is a complete bundle of the Private Key and the Public key and other certificates in the certificate chain.)
• Regardless of the type of keystore employed, a keystore must have the complete chain of certs.
• Complete chain of certs include A Public Key of the CA-signed/Self Signed certificate, Private key matching the former, Public Key of the Root CA and the Public Key(s) of the intermediate CA(s).

Truststore:

• Many RadiantOne installed components (e.g. Control Panel) act as client’s to the local RadiantOne FID and might require SSL access. Therefore, any time you change the RadiantOne FID server certificate, you must import the corresponding public key certificate into the Client Certificate Trust Store (unless the signer of the server certificate is already trusted).

• Also, the certificates in the Client Certificate Trust Store are used by RadiantOne FID to connect via SSL to underlying data sources. Therefore, the appropriate client (public key) certificate (associated with the server certificate of the backend) needs imported into the Client Certificate Trust Store (unless they are signed by a trusted/known Certificate Authority).

Keystore Password:

• During installation, RadiantOne creates a keystore (as described above). A new keystore can also be generated on demand using the Genkey Command. ( Mentioned later in the article.)
• In both cases, the keystore is created with the default password radiantlogic.
• If needed, this password can be updated in one of the following ways:

-- Via the Server Control Panel
Go to Settings → Server Certificate Password, update the value, then save and restart the service.

-- Via the Command Line
Use the Java Keytool Utility.

keytool -keypasswd -keystore rli.keystore -storepass radiantlogic -alias rli

Note: The -keypasswd option requires the current password.

Further troubleshooting steps for keystore password-related errors are provided in the following article: Invalid keystore password or keystore password was incorrect

Note: If you are unsure how to edit ZK properties or are unfamiliar with Zookeeper, please contact Radiant Logic Support. Incorrect modifications to ZK can cause fatal cluster failures and make troubleshooting significantly more difficult.

Certificate Signing Request (CSR):

• A certificate signing request (CSR) is one of the first steps towards (explained later) getting your own SSL/TLS certificate. Generated on the same server you plan to install the certificate on, the CSR contains information (e.g. common name, organization, country) the Certificate Authority (CA) will use to create your certificate. It also contains the public key that will be included in your certificate and is signed with the corresponding private key (explained below).

Server Public Key:

• A Public Key is issued in .cer format which is obtained from the CA using the CSR and in the case of CA-signed/Self Signed certificate is issued for the host/server where the keystore resides( Subject Alternative Names or SANs included allow reusing the keystore for the all the hostnames listed as SANs).
• During the RadiantOne installation, a default self-signed certificate is generated for RadiantOne FID. This self-signed certificate can be replaced with one assigned by a Certificate Authority (CA).
• If RadiantOne FID is deployed in a cluster, and each node has their own server certificate ( Unless Subject Alternative Names are specified for the nodes of the cluster. The same server cert can be used for all the nodes of the cluster.)
• Make sure the certificate is created with ServerAuth & ClientAuth extended key usage.
• DELETING THE PUBLIC KEY ENTRY WILL ALSO DELETE THE PRIVATE KEY. DELETING ENTRIES FROM RLI KEYSTORE IS NOT RECOMMENDED.

Server Private Key:

• Private key matching the public key ( CA-signed/Self Signed certificate ) issued for the host/server will be present in the keystore with the default alias "rli".
• DELETING THE PUBLIC KEY ENTRY WILL ALSO DELETE A PRIVATE KEY. DELETING ENTRIES FROM RLI KEYSTORE IS NOT RECOMMENDED. 

Java Keytool:

• RadiantOne installation comes with a java keytool which is a command line utility which can be used for performing read/modify operation of keystore entries and certain properties.
• Keytool file is present in RLI_HOME/jdk/jre/bin

Procedures

Importing/Replacing a CA-signed certificate (JKS)

High-Level Steps for Replacing the SSL certificates:

1. GENKEY ( SKIP TO STEP 2. for renewals)
2. CSR
3. IMPORT CHAIN ONTO KEYSTORE.
4. VERIFY KEYSTORE PASSWORD
5. IMPORT CHAIN ONTO TRUSTSTORE

1. Generate a keystore with the default public and private key⇒GENKEY. Y ( SKIP TO STEP 2. for renewals)

The following generates a Keystore with a public key(.cer) & private key ( encrypted entry inside the keystore) pair:

          a.For the single cluster node/standalones

keytool -genkey -alias rli -keyalg RSA -keystore $RLI_HOME/vds_server/conf/rlivds.keystore 
-dname "cn=<FQDN>"

          b. For having Subject Alternative Names(SAN):

keytool -genkey -alias rli -keyalg RSA 
-keystore C:\radiantone\vds\vds_server\conf\rlivds.keystore -storepass radiantlogic 
-dname “cn=<FQDN>" -ext SAN=dns:<FQDN>,ip:<host_IP>

2. Generate a CSR:⇒CSR

keytool -certreq -alias rli -keystore $RLI_HOME/vds_server/conf/rlivds.keystore 
-file $RLI_HOME/vds_server/conf/vdsserver.csr -ext SAN=dns:<FQDN>,ip:<host_IP>

A sample CSR look like:

3. IMPORT CHAIN ONTO KEYSTORE.

After the certs (Public keys) are obtained (BY THE CUSTOMER), the cert has to be
imported into the keystore⇒IMPORT CHAIN ONTO KEYSTORE.
Stop VDS and Control Panel Services.

Root CA cert:

$RLI_HOME\jdk\jre\bin\keytool -import -trustcacerts -alias rootca -file <root>.crt -
keystore rli.keystore

Intermediate CA cert:

$RLI_HOME\jdk\jre\bin\keytool -import -trustcacerts -alias interca -file <issuing>.crt -
keystore rli.keystore

The Server CA cert\SAN CA cert:

$RLI_HOME\jdk\jre\bin\keytool -import -trustcacerts -alias rli -file <client>.cer -keystore
rli.keystore

This will REPLACE the PUBLIC KEY and matching the PRIVATE KEY is already
present in the keystore.

4. Verify the password equivalence:⇒VERIFY KEYSTORE PASSWORD

$RLI_HOME\jdk\jre\bin\keytool -keypasswd -keystore rli.keystore -storepass
"radiantlogic" -alias rli -keypass "radiantlogic"

This prompting you to provide a new password means that the password is good. You can come out of it with Ctrl+C.
NOTE:
When configuring SSL, the password must be equivalent in three places: DEFAULT
PASSWORD: “radiantlogic”
1. The Keystore password

2. The Certificate key password (set in the certificate)
3. The Password used by VDS to access both the Keystore and the certificate. (automatically updated upon setting the password in Server Control Panel as shown in the above screenshot. RLI_HOME/vds_server/conf/jetty/config.properties)

This password can be encrypted using RLI_HOME/bin/VDSUtility.exe==⇒Option 9

5. IMPORT CHAIN ONTO TRUSTSTORE:

• Copy the Keystore files (rli.keystore) across 0all the nodes and Start back all the
  stopped services.
• Import the entire cert chain into Settings > Security > Client Certificate
  Truststore:⇒IMPORT ONTO TRUSTSTORE (ALSO CAN BE DONE AS STEP 1;
  SLIGHTLY BETTER APPROACH)

Java Keytool

• Present in $RLI_HOME\jdk\jre\bin\keytool.exe

Common Keytool Commands

• keytool -genkey -alias rli -keyalg RSA -keystore
  /home/administrator/radiantone/vds/vds_server/conf/rli.keystore -dname
  "cn=server_fqdn"⇒GENKEY
• keytool -certreq -alias rli -keystore
  /home/administrator/radiantone/vds/vds_server/conf/rli.keystore -file
  /home/administrator/radiantone/vds/vds_server/conf/vdsserver.csr⇒CSR
• keytool -import -file /home/administrator/Desktop/rli.p7b -keystore
  /home/administrator/radiantone/vds/vds_server/conf/rli.keystore -v -alias
  rli⇒IMPORT
• keytool -export -alias -keystore <keystore path> -file <filepath of cert>⇒EXPORT
  keytool -list -v -keystore <keystore path>⇒LIST KEYSTORE
• keytool -delete -alias <alias> -keystore <keystore path≥⇒DELETE ENTRY FROM
  KEYSTORE( EXTREME CAUTION!! DELETES BOTH PRIMARY AND PUBLIC KEY…..
  AVOID IF POSSIBLE.)
• keytool -keypasswd -keystore <Keystore path> -storepass <current keystore
  password> -alias <aliasname> -keypass <keypassword> (to check if keypass and
  storepass are equal)
• keytool -keypasswd -keystore <keystore path> -storepass <current keystore
  password> -alias <aliasname> (to set new key password)
• keytool -storepasswd -keystore <keystore path> (to set new keystore password)
• keytool -importkeystore -srckeystore pfxfile.pfx -srcstoretype PKCS12 -
  deststoretype JKS -destkeystore rlinew.keystore ( IMPORT ONE KEYSTORE
  ONTO ANOTHER)
• keytool -changealias -keystore <path to keystore> -alias <old alias> -destalias <new
  alias> (CHANGE ALIAS)

List of checks for PKCS 12(.PFX) 

1. Check whether the PKCS package has an alias. Preferably it must be "rli"
2. The password for the store must be radiantlogic (default).
3. When configuring SSL, the password must be equivalent in three places:
The keystore password
The certificate key password
The password used by VDS to access both the keystore, and the certificate. (This
password needs to be updated from the Server Control Panel> Settings> Certificate
key password)
NOTE: The ERROR (Keystore has been tampered with…) is thrown when the passwords
do not match in all 3 locations. (The command to check password equivalence is mentioned previously in procedures section.)

If the common name is wrong in the certificate:

The steps are basically as simple as :
1. Replace the new rli.keystore (JKS) with the entire PKCS12(.pfx) package (obtained by the customer)
2. This has to be replaced in the server control panel on the certificate path/type
3. This upon restart updates the jetty config file.

Interactive Summary

keytool -genkey -alias rli -keyalg RSA \
  -keystore $RLI_HOME/vds_server/conf/rlivds.keystore \
  -dname "cn=<FQDN>"

keytool -genkey -alias rli -keyalg RSA \
  -keystore $RLI_HOME/vds_server/conf/rlivds.keystore -storepass radiantlogic \
  -dname "cn=<FQDN>" -ext SAN=dns:<FQDN>,ip:<host_IP>

keytool -certreq -alias rli \
  -keystore $RLI_HOME/vds_server/conf/rlivds.keystore \
  -file $RLI_HOME/vds_server/conf/vdsserver.csr \
  -ext SAN=dns:<FQDN>,ip:<host_IP>

keytool -import -trustcacerts -alias rootca \
  -file <root>.crt -keystore rli.keystore

keytool -import -trustcacerts -alias interca \
  -file <issuing>.crt -keystore rli.keystore

keytool -import -trustcacerts -alias rli \
  -file <client>.cer -keystore rli.keystore

keytool -keypasswd -keystore rli.keystore \
  -storepass "radiantlogic" -alias rli -keypass "radiantlogic"

Server Control Panel → Settings → Security → Client Certificate Truststore

keytool -importkeystore \
  -srckeystore file.pfx -srcstoretype PKCS12 \
  -destkeystore rlinew.keystore -deststoretype JKS