Configuring a Third-Party Root CA custom certificate for HTTPS agent communications

You might want to configure HTTPS communication for agents to use third-party Certificate Authority (CA) issued certificates if this is required by your local security policy.

If you want to use a certificate that is generated by a third-party CA, complete the following steps:

1. Log in to the Cloud APM server and create your own keystore working directory under /opt/ibm/ccm (such as /opt/ibm/ccm/working_directory). Alternatively, use the existing /opt/ibm/ccm/keyfiles directory and keep your keyfiles directories unique by selecting hostname parameters other than default.server, default.agent, and apmCA. These working directories are used by the installer to create the self signed certificate keyfiles that are used by default. The hostname value is used as the name of the subdirectory to store the keystore files. You specify the hostname value in the create_security_artifacts.sh.

   During a reinstallation of the Cloud APM server, if the installer finds an existing /opt/ibm/ccm/keyfiles directory, it will not replace the keyfiles in this directory. But if an alternative directory other than /opt/ibm/ccm/keyfiles was used during the previous installation, the keyfiles are replaced. For example, if you used a subdirectory of /keyfiles, these keyfiles are replaced during the reinstallation.

   In subsequent steps, the create_security_artifacts.sh script creates a Certificate Signing Request (CSR) in the working_directory/exports directory as an .arm file. You must send the .arm file to your third-party CA for signing. Your third-party CA returns your new certificate, the issuing certificate, and any other certificates in the issuer's certificate chain of trust.

   The create_security_artifacts.sh script also creates a set of files in the working_directory/keyfiles directory that need to be updated when you get your certificates back from the third-party CA and import them into the keystore. These files are important to keep.

2. To create the agent keystore and CSR, first set the APMPASS environment variable to the keystore password.
   This variable is used by the create_security_artifacts.sh script. Example:

   export APMPASS="put_your_agent_keystore_password_here"

3. Create the agent keystore and CSR.
   Because the agent certificate is used by all agents, create a generic hostname by using the Cloud APM server hostname. We recommend incorporating the Cloud APM server hostname for easy identification. The value that is used for the hostname parameter will become the name of the subdirectory in /working_directory where the agent keystore and CSRs are created.

   For the following examples, the Cloud APM server hostname variable is serverhostname. If your Certificate Authority requires a Subject Alternative Name (SAN) in the CSR request, add the -san_name parameter followed by the DNS domain name for your agents (for example, ibm.com) to the /opt/ibm/ccm/create_security_artifacts.sh command. If you need to specify multiple DNS domain names with the -san_name parameter, separate each domain name with a comma.

   The -keyalg EC parameter indicates that your third party CA uses ciphers that are compliant with the Suite-B security standard. By default, the following cipher suite is accepted by the Cloud APM server: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256. You must ensure that all the certificates in the chain of trust contain the namedCurve parameter with the name of the curve that is used for signing: (rfc 5480 section 2.1.1 states that implicitCurve and specifiedCurve must not be used in PKIX). If your third-party CA only supports the RSA signature algorithm, specify -keyalg RSA in place of -keyalg EC.

   Set the -dname parameter to a standard x509 name that identifies your domain. For example,

   /opt/ibm/ccm/create_security_artifacts.sh -gencsr -workdir /opt/ibm/ccm/keyfiles -keyalg EC -hostname serverhostname.agent  
   -dname OU=ou,O=o,L=l,ST=st,C=c -label APM_Agent_Certificate

   You receive the following message:

   Certificate signing request has been created and is available in the following file: /opt/ibm/ccm/keyfiles/serverhostname.agent/exports/serverhostnameagent.arm
   Send it to your Certificate Authority for signing

4. If your server keystore password is different from the agent password, unset the APMPASS variable and reexport it using the server password.
   Example:

   export -n APMPASS

   export APMPASS ="put_your_server_keystore_password_here"

5. Create the server keystore and CSR:

   /opt/ibm/ccm/create_security_artifacts.sh -gencsr -workdir /opt/ibm/ccm/keyfiles -keyalg EC -hostname serverhostname  
   -dname OU=ou,O=o,L=l,ST=st,C=c -label APM_Server_Certificate

   You receive the following message:

   Certificate signing request has been created and is available in the following file: /opt/ibm/ccm/keyfiles/serverhostname/exports/myhost.com.arm
   Send it to your Certificate Authority for signing.

   Creating the CSRs also creates a private key that is initially in the working_directory/keyfiles/keyfile.rdb file. It is moved to the keyfile.kdb file later when you import the certificate. All other keyfiles must remain in the working_directory/keyfiles/ directory because they are used in subsequent steps, even though you specify only the path to the keyfile.kdb file.

   Note:

   • The -keyalg EC parameter indicates that your third party CA uses ciphers that are compliant with the Suite-B security standard. By default, the following cipher suite is accepted by the Cloud APM server: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256. You must ensure that all the certificates in the chain of trust contain the namedCurve parameter with the name of the curve that is used for signing: (rfc 5480 section 2.1.1 states that implicitCurve and specifiedCurve must not be used in PKIX). If your third-party CA only supports the RSA signature algorithm, specify -keyalg RSA in place of -keyalg EC.
   • If your Certificate Authority requires a Subject Alternative Name (SAN) in the CSR request, add the -san_name parameter followed by the Cloud APM server hostname to the /opt/ibm/ccm/create_security_artifacts.sh command. If you need to specify multiple hostnames with the -san_name parameter, separate each hostname with a comma.
6. Send the CSR files to the private third-party CA for signing. Copy all certificates you receive for both the server and agent back to the working_directory/exports directory for safe keeping.
   1. Copy the server, signer, and root certificates to the following directory: /opt/ibm/ccm/keyfiles/serverhostname/exports
   2. Copy the agent, signer, and root certificates to the following directory: /opt/ibm/ccm/keyfiles/serverhostname.agent/exports
   If you are working with certificates for only a brief amount of time, such as when you are waiting for your CA to create certificates, you should unset APMPASS or logout of your session. These steps remove the password from the environment. Ensure that the APMPASS environment variable is set appropriately when running the create_security_artifacts.sh script.
7. Add your third-party CA root certificate to the agent and server keystore.kdb files unless the root certificate is the signing certificate.
   If your chain of trust contains only the single certificate, then the signing certificate is the root certificate and you can skip this step.

   /opt/ibm/ccm/create_security_artifacts.sh –addkeytodb -destkdb working_directory/keyfiles/keyfile.kdb -importfile your_CA’s_root_cert_path -label your_CA’s_root_label

   1. Example for the agent:

      /opt/ibm/ccm/create_security_artifacts.sh -addkeytodb -destkdb /opt/ibm/ccm/cust_certs/custom.agent/keyfiles/keyfile.kdb -importfile /opt/ibm/ccm/keyfiles/serverhostname.agent/exports/rootca.crt -label RootCA

      You receive the following message:

      Certificate added successfully.

   2. Example for the server:

      /opt/ibm/ccm/create_security_artifacts.sh -addkeytodb -destkdb /opt/ibm/ccm/keyfiles/myhost.com/keyfiles/keyfile.kdb -importfile /opt/ibm/ccm/keyfiles/serverhostname/exports/rootca.crt -label RootCA

      You receive the following message:

      Certificate added successfully.

8. (Optional) Add your third-party CA intermediate certificate that is not the issuing (Signer) certificate:

   /opt/ibm/ccm/create_security_artifacts.sh -addkeytodb -destkdb working_directory/keyfiles/keyfile.kdb -importfile your_CA’s_intermediate_cert_path -label your_CA’s_intermediate_label

   Repeat this step for any intermediate certificates your third-party CA provides that are not the issuing certificate.
9. Import your new certificate and the signing certificate. This command is unusual because it uses rootca for the parameter names of the signer, and Root CA certificates are not usually the signers when a private third-party CA is issuing your certificates.

   /opt/ibm/ccm/create_security_artifacts.sh -importcert -rootcacert path_to_CAissuer_certificate -rootcalabel issuer_certificate_label -destkdb working_directory/hostname/keyfiles/keyfile.kdb -importfile path_to_new_signed_certificate

   1. Add your new server certificate to the server keystore.kdb file:

      /opt/ibm/ccm/create_security_artifacts.sh  -importcert -importfile /opt/ibm/ccm/keyfiles/serverhostname/exports/server.crt  -rootcacert /opt/ibm/ccm/keyfiles/serverhostname/exports/signca.crt  -destkdb /opt/ibm/ccm/keyfiles/serverhostname/keyfiles/keyfile.kdb -rootcalabel "SignerCA"

      You receive the following message:

      Certificate import successful.

   2. Add your new agent certificate to the agent keystore.kdb file:

      /opt/ibm/ccm/create_security_artifacts.sh  -importcert -importfile /opt/ibm/ccm/keyfiles/serverhostname.agent/exports/agent.crt  -rootcacert /opt/ibm/ccm/keyfiles/serverhostname.agent/exports/signca.crt  -destkdb /opt/ibm/ccm/keyfiles/servehostname.agent/keyfiles/keyfile.kdb -rootcalabel "SignerCA"

      You receive the following message:

      Certificate import successful.

10. Add the agent certificate to the server keystore. The Cloud APM server is configured to accept connections only from clients or agents that authenticate themselves with a known certificate.

    /opt/ibm/ccm/create_security_artifacts.sh -addkeytodb -destkdb /opt/ibm/ccm/keyfiles/serverhostname/keyfiles/keyfile.kdb -importfile /opt/ibm/ccm/keyfiles/serverhostname.agent/exports/serverhostname.agent.crt -label "APM_Agent_Certificate"

11. Add the server certificate to the agent keystore so that the agent is able to authenticate to the server:

    /opt/ibm/ccm/create_security_artifacts.sh -addkeytodb -destkdb /opt/ibm/ccm/keyfiles/serverhostname.agent/keyfiles/keyfile.kdb -importfile /opt/ibm/ccm/keyfiles/serverhostname/exports/serverhostname.crt -label "APM_Server_Certificate"

12. Convert the agent and server keystores from the GSKit format (*.kdb) to the Java™ keystore format (*.jks).
    Agent example:

    /opt/ibm/ccm/create_security_artifacts.sh -kdb2jks -sourcekdb /opt/ibm/ccm/keyfiles/serverhostname.agent/keyfiles/keyfile.kdb
    

    The /opt/ibm/ccm/keyfiles/serverhostname.agent/keyfiles/keyfile.jks file is created.
    Server example:

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

    The /opt/ibm/ccm/keyfiles/serverhostname/keyfiles/keyfile.jks file is created.
13. Remove the keystore password from the environment:

    export -n APMPASS

14. The keyfiles that are used by the Cloud APM server for agent communication are in the /opt/ibm/wlp/usr/server/min/resources/security directory. Back up the key.jks file already there and replace it with your new version.

    cp /opt/ibm/wlp/usr/servers/min/resources/security/key.jks /opt/ibm/wlp/usr/servers/min/resources/security/key.jks.orig
    cp /opt/ibm/ccm/keyfiles/serverhostname/keyfiles/keyfile.jks /opt/ibm/wlp/usr/servers/min/resources/security/key.jks

    If you previously added a third-party CA certificate to the key.jks file to forward events that use an SSL connection to your SMTP Server, you must re-add the third-party CA certificate to the new keystore. For instructions, see Event Manager in Advanced Configuration.
15. Encode the (xor) server keystore password:

    /opt/ibm/wlp/bin/securityUtility encode

    The next few steps involve user-exit.xml, which is an override file for server.xml.
16. If it is not already in user-exit.xml, move the <ssl> element with the "defaultKeyStore" definition of the keystore from server.xml:
    1. Copy the <keyStore> xml element that contains the "defaultKeyStore" definition of the keystore from install_dir/wlp/usr/servers/min/server.xml to install_dir/wlp/usr/servers/min/user-exit.xml.
    2. Replace the value of the password attribute in user-exit.xml with the newly encoded password from step 15.
    3. Remove the <keyStore> xml element from the server.xml file.
17. Move and configure the <ssl> element that contains the enabledCiphers attribute from server.xml to user-exit.xml:
    1. Copy the <ssl> xml element with the enabledCiphers attribute from the install_dir/wlp/usr/servers/min/server.xml file to install_dir/wlp/usr/servers/min/user-exit.xml.
    2. In user-exit.xml, add new line clientAuthentication="true" after the enabledCiphers line.
    3. Remove the <ssl> xml element from the server.xml file.
    4. If your third-party CA provides only an RSA signature, set enabledCiphers="" instead of enabledCiphers="TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256" in user-exit.xml, since your certificate does not support Elliptical Curve encryption.
18. Update the certificate labels in the Cloud APM server install_dir/wlp/usr/servers/min/user-exit.xml file and edit as shown:

    serverKeyAlias="APM_Server_Certificate"
    clientKeyAlias="APM_Agent_Certificate"

    If the serverKeyAlias and the clientKeyAlias key alias entries do not exist in the user-exit.xml file, you must add the entries to the <ssl> section after the line with the enabledCiphers attribute..
19. Restart the Cloud APM server:

    apm stop min

    apm start min

20. If the Hybrid Gateway is installed in your Tivoli® Monitoring environment, copy the JKS agent keystore to the Hybrid Gateway location:

    /opt/ibm/wlp/usr/servers/hybridgateway/resources/security/

21. Complete one of the following steps to install the agent keyfiles, depending on whether you installed agents:
    • If you installed agents, reconfigure the existing agents to use the new certificates by following the steps in Configuring agents to connect to a different server or to use HTTPS communication.
    • Before you install new agents, use the agent configuration tool to modify the agent images to contain the new certificates.
      1. To create the configuration packages, use the /opt/ibm/ccm/make_configuration_packages.sh tool, including the -k parameter to specify the location of agent keystore files. For more information, see step 2 in Configuring the downloaded images.
      2. To configure the agent images, use the /opt/ibm/ccm/configure_agent_images script.
      3. Unpack the resulting agent image and modify the configuration file to show which certificate should be used by the agents:
         • The KDEBE_KEY_LABEL = agent_key_label variable must be added to the configuration files in an unpacked agent image:

           For example, KDEBE_KEY_LABEL="APM_Agent_Certificate".

           If your third-party CA provides only an RSA signature, change KDEBE_FIPS_MODE_ENABLED=SuiteB-128 to KDEBE_FIPS_MODE_ENABLED=NO.
         • On Linux/AIX, modify the variable in the following file: unpacked_agent_image_path/.apm_config/agent_global.environment.

           For example, APM_Agent_Install_8.1.4.0/.apm_config/agent_global.environment.

         • On Windows, modify the variable in the [CMA_CONFIG_VARIABLES] section of the following file: unpacked_agent_image_path\apm_config\framework_silent_install.txt.
         • Compress the unpacked agent installation image.
      The agent configuration package that you create with the make_configuration_packages.sh script also contains the Windows package with the configuration data and the Windows script.
22. You must configure the Cloud APM server agents to use HTTPS and certificates. See Configuring the communications protocol for server agents for instructions.