Configuring certificates by using a private root certificate authority

Edit online

You can use the Cloud APM server to create a private root certificate authority (CA) file and use it to sign the certificates that are used by the server processes. Your Cloud APM console users must then import the private root CA certificate into the trusted root certificate authorities list in their browsers so that the Cloud APM certificates are trusted by their browsers.

About this task

Use the default /opt/ibm as the directory where you installed the Cloud APM server or use the path that you specified for installation.
Replace apm_server_hostname with the host name of the Cloud APM server. Use the fully qualified host name (such as myapmserver.ibm.com) unless Cloud APM console users are able to use the short host name (such as myapmserver). For example, replace Signer_CA_on_apm_server_hostname in the following steps with Signer_CA_on_myapmserver.ibm.com.
Replace password in the following steps with either ROOTCAPASS, which is the root certificate authority password or APMPASS, which is the password of the Cloud APM server UI keystore.
Replace my company name with your company name, for example IBM®.
You have two choices for the key algorithm: RSA or Elliptic Curve (EC). The algorithm that is used by the CA for signing its root and intermediate certificates must match the algorithm that is specified by the -keyalg parameter. The procedure assumes that the RSA algorithm is used. If the root CA certificate was signed using the Elliptic Curve algorithm, replace -keyalg RSA with -keyalg EC in every step of this procedure where a key algorithm is specified. The use of Elliptic Curve is encouraged because it supports forward secrecy and does not rely on static keys.
The new certificates expire 10 years after they are created.

Procedure

Create the private root certificate authority certificate:

export ROOTCAPASS="password"

/opt/ibm/ccm/create_security_artifacts.sh -genrootca -workdir "/opt/ibm/ccm/uikeyfiles" -keyalg RSA -hostname Root_CA_on_apm_server_hostname -dname "O=my company name" -label "Root_CA_for_APM_UI"

Generate the certificate signing request (CSR) for the signer certificate authority:

export APMPASS="password"

/opt/ibm/ccm/create_security_artifacts.sh -gencsr -workdir /opt/ibm/ccm/uikeyfiles -keyalg RSA -hostname Signer_CA_on_apm_server_hostname -dname "O=my company name" -label "Signer_CA_for_APM_UI"

Import the root CA certificate into the signer CA key database:

/opt/ibm/ccm/create_security_artifacts.sh -addkeytodb -destkdb /opt/ibm/ccm/uikeyfiles/Signer_CA_on_apm_server_hostname/keyfiles/keyfile.kdb -importfile /opt/ibm/ccm/uikeyfiles/apmCA/exports/apmCA.cer -label "Root_CA_for_APM_UI"

Sign the signer CA certificate:

/opt/ibm/ccm/create_security_artifacts.sh -signcsr -keyalg RSA -rootcakdb /opt/ibm/ccm/uikeyfiles/apmCA/keyfiles/keyfile.kdb -rootcalabel "Root_CA_for_APM_UI" -csrfile /opt/ibm/ccm/uikeyfiles/Signer_CA_on_apm_server_hostname/exports/Signer_CA_on_apm_server_hostname.arm -ca true

Generate the certificate signing request (CSR) for the Cloud APM server certificate:
```
/opt/ibm/ccm/create_security_artifacts.sh -gencsr -workdir /opt/ibm/ccm/uikeyfiles -keyalg RSA -hostname apm_server_hostname -dname "O=my company name" -san_name apm_server_hostname -label "defaultKeyStore"
```
You must specify defaultKeyStore as the label so that you do not have to edit the keystore alias in the server.xml file for the apmui, server1, uviews, and oidc processes.

Add the root CA certificate into the key database for the Cloud APM server certificate:

/opt/ibm/ccm/create_security_artifacts.sh -addkeytodb -destkdb /opt/ibm/ccm/uikeyfiles/apm_server_hostname/keyfiles/keyfile.kdb -importfile /opt/ibm/ccm/uikeyfiles/apmCA/exports/apmCA.cer -label "Root_CA_for_APM_UI"

Add the signer CA certificate into the key database for the Cloud APM server certificate:

/opt/ibm/ccm/create_security_artifacts.sh -addkeytodb -destkdb /opt/ibm/ccm/uikeyfiles/apm_server_hostname/keyfiles/keyfile.kdb -importfile /opt/ibm/ccm/uikeyfiles/Signer_CA_on_apm_server_hostname/exports/Signer_CA_on_apm_server_hostname.cer -label "Signer_CA_for_APM_UI"

Sign the Cloud APM server certificate using the signer CA:

/opt/ibm/ccm/create_security_artifacts.sh -signcsr -keyalg RSA -rootcakdb /opt/ibm/ccm/uikeyfiles/Signer_CA_on_apm_server_hostname/keyfiles/keyfile.kdb -rootcalabel "Signer_CA_for_APM_UI" -csrfile /opt/ibm/ccm/uikeyfiles/apm_server_hostname/exports/apm_server_hostname.arm

Convert the Cloud APM server signed certificate to the JKS format:

/opt/ibm/ccm/create_security_artifacts.sh -kdb2jks -sourcekdb /opt/ibm/ccm/uikeyfiles/apm_server_hostname/keyfiles/keyfile.kdb

To remove the passwords from the command line environment, enter these commands:
```
export -n APMPASS
```
```
export -n ROOTCAPASS
```

Copy the Cloud APM server signed certificate to the shared location for the apmui, server1, uviews, and oidc processes:

cp /opt/ibm/wlp/usr/shared/resources/security/key.jks /opt/ibm/wlp/usr/shared/resources/security/key.jks.sav

cp /opt/ibm/ccm/uikeyfiles/apm_server_hostname/keyfiles/keyfile.jks /opt/ibm/wlp/usr/shared/resources/security/key.jks

Encode the APMPASS password value from step 3 by using the Liberty securityUtility tool and AES cipher:
```
/opt/ibm/wlp/bin/securityUtility encode --encoding=aes password
```
Update the keystore password in the /opt/ibm/wlp/usr/shared/config/serverVariables.xml file:
1. Search for the line that contains key.store.password.
2. Replace the value with the output from the previous step (step 12).

Update the oidc entry in the shared truststore with the new Cloud APM server signed certificate:

cp /opt/ibm/wlp/usr/shared/resources/security/trust.jks /opt/ibm/wlp/usr/shared/resources/security/trust.jks.sav

/opt/ibm/java/jre/bin/keytool -delete -alias oidc -keystore /opt/ibm/wlp/usr/shared/resources/security/trust.jks -storepass 'ccmR0cKs!'

/opt/ibm/java/jre/bin/keytool -importcert -alias oidc -file /opt/ibm/ccm/uikeyfiles/apm_server_hostname/exports/apm_server_hostname.cer -noprompt -keystore /opt/ibm/wlp/usr/shared/resources/security/trust.jks -storepass 'ccmR0cKs!'

where ccmR0cKs! is the default truststore password. If you want to use a different password, follow the procedure in Changing the password for the shared truststore and use the new password in this step.

If you want to limit which cipher suites are negotiated by your Cloud APM console users and the Cloud APM server, perform these steps:
1. Copy the <ssl> element and all of its attributes from the /opt/ibm/wlp/usr/servers/apmui/server.xml file to the apmui/user-exit.xml file, and then delete the <ssl> element and its attributes from the apmui/server.xml file.
  For example, copy all of these lines from apmui/server.xml to apmui/user-exit.xml, and then delete the lines from apmui/server.xml:
```
<ssl
        id="defaultSSLConfig"
        sslProtocol="TLSv1.2"
        keyStoreRef="defaultKeyStore"
        trustStoreRef="sharedTrustStore"
        enabledCiphers=""
        serverKeyAlias="" />
```
2. In the apmui/user-exit.xml file, change the value of the enabledCiphers attribute to the following value if you specified -keyalg RSA in step 1.c.
```
enabledCiphers="TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
```
  Otherwise, change the value of the enabledCiphers attribute to the following if you specified -keyalg EC in step 1.c.
```
enabledCiphers="TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256"
```
  Note: If these cipher suite combinations are too restrictive for your Cloud APM console users, you can choose other cipher suite combinations that are compatible with the signature algorithm (RSA or EC) that you chose in step 1.c. The Cloud APM server installs IBM Java™ 8, and IBM Java determines the cipher suites that can be used for Cloud APM. For the list of IBM Java 8 supported cipher suites, see Cipher suites. Choose ones that can be used for TLS 1.2 and that are compatible with your signature algorithm.
3. Repeat steps 15.a and 15.b for these files:
  - /opt/ibm/wlp/usr/servers/oidc/server.xml and oidc/user-exit.xml
  - /opt/ibm/wlp/usr/servers/server1/server.xml and server1/user-exit.xml
  - /opt/ibm/wlp/usr/servers/uviews/server.xml and uviews/user-exit.xml
Note: The content of the <ssl> element in the apmui/server.xml, oidc/server.xml, server1/server.xml, and uviews/server.xml files is slightly different. Copy the content of the <ssl> element in each server.xml file to the corresponding user-exit.xml file, and then update the enabledCiphers attribute as described.
Add the root CA certificate to the Java truststore:
1. Enter the following command:
```
/opt/ibm/java/bin/keytool -importcert -file /opt/ibm/ccm/uikeyfiles/apmCA/exports/apmCA.cer -keystore /opt/ibm/java/jre/lib/security/cacerts -alias Root_CA_for_APM_UI
```
2. After you are prompted, enter the keystore password:
```
changeit
```
3. After you are prompted to trust this certificate, enter yes.
Restart the Cloud APM server processes:
```
apm restart_all
```
Send the /opt/ibm/ccm/uikeyfiles/apmCA/exports/apmCA.cer and /opt/ibm/ccm/uikeyfiles/Signer_CA_on_apm_server_hostname/exports/Signer_CA_on_apm_server_hostname.cer files to your Cloud APM console users.
- Users must import the apmCA.cer file into the trusted root certificate list in their browsers and indicate that the browser should trust this certificate to identify websites.
- They must also import the Signer_CA_on_apm_server_hostname.cer file into the intermediate certificate authorities list if it exists and indicate that the browser should trust this certificate to identify websites. If the browser does not have an intermediate certificate authorities list, then users should import the certificate into the trusted root certificate list.
- The steps to import the root certificate authority depend on the browser and browser version. For more information, see your web browser documentation.

Results

After Cloud APM console users import the private root certificate and signer certificate, they no longer see certificate errors that indicate the Cloud APM server certificates are not signed by a trusted root certificate authority.