Configuring certificates by using a Third-Party Root Certificate Authority

Edit online

You can create a custom certificate that is not signed by you but is generated by a third-party root certificate authority (CA).

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 Certificate Signing Request (CSR):
1. Add your keystore password to the environment:
```
export APMPASS="password"
```
  where password is the administrator password for the Cloud APM server.
2. Create a uikeyfiles directory to hold the files that are associated with your CSR, under /opt/ibm/ccm:
```
mkdir /opt/ibm/ccm/uikeyfiles
```
  These files are included during the Cloud APM server backup and restore procedures.
3. Run the following script:
```
./create_security_artifacts.sh -gencsr -workdir /opt/ibm/ccm/uikeyfiles -keyalg RSA -hostname apm_server_hostname -dname OU=ou,O=o,L=l,ST=st,C=c -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.
A CSR is created in /opt/ibm/ccm/uikeyfiles/apm_server_hostname/exports/apm_server_hostname.arm that you send to have signed by your CA. Your CA returns your new certificate, the issuing certificate, and any other certificates in the issuer certificate chain of trust. It also creates a set of files in /opt/ibm/ccm/uikeyfiles/apm_server_hostname/keyfiles that need to be updated when you get your certificates back from the third-party CA and import them into opt/ibm/ccm/uikeyfiles/apm_server_hostname/keyfiles/keyfile.kdb. These files are important to keep and are reused in the steps that follow.

Some of the more recent versions of Chrome require imported certificates to specify a Subject Alternate DNS name. If your CA does not add the Subject Alternate Name automatically, you can add it to the CSR with the -san_name parameter. If you need to specify multiple hostnames, separate each hostname with a comma. If your certificate is generated without a Subject Alternate DNS Name, Chrome users need to override the warning message when they start the Cloud APM console.

The -gencsr parameter creates a private key that is, for now, in the keyfile.rdb file. It is moved to the keyfile.kdb later when you run the import.
After your certificates are returned, add the root, any intermediates, and the issuing certificate into the keyfile.kdb that was created with the -gencsr parameter:
1. Add your CA’s root certificate:
```
/opt/ibm/ccm/create_security_artifacts.sh –addkeytodb -destkdb /opt/ibm/ccm/uikeyfiles/apm_server_hostname/keyfiles/keyfile.kdb -importfile your_CA's_root_cert_path -label your_CA's_root_label
```
  Where your_CA's_root_cert_path is the path to the location of the root certificate file that you obtained from the third party CA and copied to the Cloud APM server, for example, /opt/ibm/mycert-files/root.crt or /opt/ibm/mycert-files/root.cer and your_CA's_root_label is a unique label to identify the CA root certificate in the Cloud APM keystore. Enter a unique string for the label, for example, Root_CA_for_APM_UI.
2. Add your CA’s intermediate certificate (if needed):
```
/opt/ibm/ccm/create_security_artifacts.sh -addkeytodb -destkdb /opt/ibm/ccm/uikeyfiles/apm_server_hostname/keyfiles/keyfile.kdb -importfile your_CA's_intermediate_cert_path -label your_CA's_intermediate_label
```
  Where your_CA's_intermediate_cert_path is the path to the location of the intermediate certificate files that you obtained from the third party CA and copied to the Cloud APM server, for example, /opt/ibm/mycert-files/intermediate.crt or /opt/ibm/mycert-files/intermediate.cer and your_CA's_intermediate_label is a unique label to identify an intermediate certificate in the Cloud APM keystore (if you have intermediate certificates). Enter a unique string for the label, for example, Intermediate_Cert_for_APM_UI.
All of the other key files must also be in that directory because they are used by the next steps, even though you specify only the path to the keyfile.kdb file. Thus, you first add the certificates to build the chain of trust.
Import your new certificate and the signing certificate.
```
/opt/ibm/ccm/create_security_artifacts.sh -importcert -rootcacert path_to_CA_issuer_cert -rootcalabel issuer_cert_label -destkdb /opt/ibm/ccm/uikeyfiles/apm_server_hostname/keyfiles/keyfile.kdb -importfile path_to_new_signed_certificate
```
This command is unusual because it uses rootcalabel and rootcacert for the parameter names that correspond to the signer certificate.
Where issuer_cert_label is a unique label to identify the signer certificate in the Cloud APM keystore. Enter a unique string for the label, for example, Issuer_for_APM_UI and path_to_new_signed_certificate is the path to the location of the signed certificate that you obtained from the third party CA and which should be used for the Cloud APM server. For example, /opt/ibm/mycert-files/my-apm-server-cert.crt or /opt/ibm/mycert-files/my-apm-server-cert.cer.

The keystore files in /opt/ibm/ccm/uikeyfiles/apm_server_hostname/keyfiles are now modified and the keyfile.kdb file can now be converted to jks format.
Convert the keyfile.kdb file to jks format:
```
/opt/ibm/ccm/create_security_artifacts.sh -kdb2jks –sourcekdb /opt/ibm/ccm/uikeyfiles/apm_server_hostname/keyfiles/keyfile.kdb 
```
Two files are created: /opt/ibm/ccm/uikeyfiles/apm_server_hostname/keyfiles/keyfile.jks and /opt/ibm/ccm/uikeyfiles/apm_server_hostname/keyfiles/keyfile.p12. The p12 file is not used for Cloud APM but openssl supports this keystore format and it can be validated by using openssl pkcs12 -in /opt/ibm/ccm/uikeyfiles/apm_server_hostname/keyfiles/keyfile.p12.
To remove the password from the command line environment, enter the following command:
```
export -n APMPASS
```

Copy the new keystore to the shared location for the apmui, server1, uviews, and oidc servers:

Back up the original keystore:

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

Copy the new keystore:

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

Run the Liberty securityUtility tool with the AES option to encode your keystore password that you added to the environment in APMPASS. Respond to the Enter text: prompt with your password.
```
/opt/ibm/wlp/bin/securityUtility encode --encoding=aes 
Enter text: 
Re-enter text: 
{aes}your_encoded_password 
```
Update the keystore password in the /opt/ibm/wlp/usr/shared/config/serverVariables.xml file by searching for the line that contains key.store.password and replace the value with the output of the previous step (step 7).
Be sure to include {aes} before your encoded password in the XML file.
Update the oidc entry in the shared truststore with your certificate:
1. Back up the original:
```
cp /opt/ibm/wlp/usr/shared/resources/security/trust.jks /opt/ibm/wlp/usr/shared/resources/security/trust.jks.orig
```
2. Remove the oidc entry:
```
/opt/ibm/java/bin/keytool -delete -alias oidc -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.
3. Add the new certificate as the oidc entry:
```
/opt/ibm/java/bin/keytool -importcert -alias oidc -file path_to_new_signed_cert -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 your third-party Root CA is not well known, add that certificate to the Java truststore:
1. Enter the following command:
```
/opt/ibm/java/bin/keytool -importcert -file path_to_Root_CA_certificate -keystore /opt/ibm/java/jre/lib/security/cacerts -alias Root_CA_certificate
```
2. After you are prompted, enter the following password:
```
changeit
```
3. After you are prompted to trust this certificate, enter yes.
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 11.a and 11.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.
Restart the Cloud APM server processes:
```
apm restart_all
```
Send the root certificate file to your Cloud APM console users.
- Users must import the root certificate into the trusted root certificate list in their browsers and indicate that the browser should trust this certificate to identify websites.
- Some browsers also require the intermediate certificates to be imported. If the browser requires it, users must import the intermediate certificate file into the intermediate certificate authorities list and indicate that the browser should trust this certificate to identify websites.
- The steps to import the root certificate authority depend on the browser and browser version. For more information, see your web browser documentation.