Configuring a self-signed certificate

You might want to configure HTTPS communication for agents to use your own certificate instead of a certificate that is generated by a third party certificate authority (CA) or the default certificate that is generated by the Cloud APM server.

If you want to use a certificate that is signed by you, complete the following steps:

1. Log in to the operating system of the Cloud APM server machine. Rename /opt/ibm/ccm/keyfiles to /opt/ibm/ccm/keyfiles-backup, and set the location of the new key files by running the following command:

   export KEYFILES_DIR=/opt/ibm/ccm/keyfiles
   

2. To generate a local root (CA) certificate authority to sign the certificate signing requests (CSRs) for the server and the agent certificates, you must choose a password. The password enciphers the root CA private key and keystore. Then, you must set the password as an environment variable. The security tool that is used for certificate management uses the password:

   export ROOTCAPASS="put_your_password_here"
   /opt/ibm/ccm/create_security_artifacts.sh -genrootca -workdir
   "${KEYFILES_DIR}" -keyalg EC -hostname 
   APM_MIN_server -dname "APM_Root_CA" -label "Root_CA_Cert" 

   Important: For step 2, 3, and 4 you can replace the key label with a different label. The following labels are used as an example only in these steps:

   • Root_CA_Cert
   • APM_Agent_Certificate
   • server_key

   You can replace the host name with a user-defined host name.

   When you are finished, you remove the password from the environment variable: enter export -n ROOTCAPASS.

   The Root CA is created in the "${KEYFILES_DIR}"/apmCA directory. It contains two subdirectories: keyfiles and exports. The keyfiles/ subdirectory contains the root CA keystore and the exports/ subdirectory contains the root CA public certificate.
3. To create the agent keystore and a CSR, you must set the host name to a generic name. You do not have to use the default.agent host name. The certificate is used by all agents that communicate with a specific server. You must create a password for the agent keystore and a private key to export to the environment before you run the script:

   export APMPASS="put_your_agent_keystore_password_here"
   /opt/ibm/ccm/create_security_artifacts.sh -gencsr -workdir "${KEYFILES_DIR}"
   -keyalg EC -hostname default.agent -dname "APM_Root_CA" -label
   "APM_Agent_Certificate"  

   A message is printed on the console that contains the path to the CSR file. After you are finished, you must remove the password from the environment variable: export -n APMPASS.
4. To create a server keystore and a CSR, you must provide a hostname for the -hostname option. It might be a generic host name such as default.server or the real hostname of the Cloud APM server. In the remaining steps in this procedure, replace default.server with the name that you specified for the -hostname option.

   export APMPASS="put_your_server_keystore_password_here"
   /opt/ibm/ccm/create_security_artifacts.sh -gencsr -workdir "${KEYFILES_DIR}"
   -keyalg EC -hostname default.server -dname "APM_Root_CA" -label "server_key"

   A message is printed on the console with the path to the CSR file. After you are finished, you must remove the password from the environment variable: export -n APMPASS.
5. Sign the agent CSR by using the root CA that you created in step 2. Then, the agent keystore signed agent certificate and the root CA public certificate is added automatically to the agent keystore:

   /opt/ibm/ccm/create_security_artifacts.sh -signcsr -keyalg EC -rootcakdb 
   "${KEYFILES_DIR}"/apmCA/keyfiles/keyfile.kdb -rootcalabel "Root_CA_Cert" 
   -csrfile 
   "${KEYFILES_DIR}"/default.agent/exports/default.agent.arm

   Important: In step 5 and 6, -rootcalabel must match the label that is specified in step 2.
6. Sign the server CSR. Then, the signed server certificate and the root CA public certificate are added automatically to the server keystore:

   /opt/ibm/ccm/create_security_artifacts.sh -signcsr -keyalg EC -rootcakdb
   "${KEYFILES_DIR}"/apmCA/keyfiles/keyfile.kdb -rootcalabel "Root_CA_Cert" 
   -csrfile 
   "${KEYFILES_DIR}"/default.server/exports/default.server.arm

7. Add the agent public key to the server keystore. The Cloud APM server 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
   "${KEYFILES_DIR}"/default.server/keyfiles/keyfile.kdb
   -importfile "${KEYFILES_DIR}"/default.agent/exports/default.agent.cer
   -label "APM_Agent_Certificate"
   

8. Add the server public key to the agent keystore so that the agent is able to authenticate server:

   /opt/ibm/ccm/create_security_artifacts.sh -addkeytodb -destkdb 
   "${KEYFILES_DIR}"/default.agent/keyfiles/keyfile.kdb -importfile
   "${KEYFILES_DIR}"/default.server/exports/default.server.cer -label "server_key"

9. Convert the server keystore from the GSKit format (*.kdb) to the Java™ keystore format (*.jks). You must set the server keystore password:

   export APMPASS="put_your_server_keystore_password_here"
   /opt/ibm/ccm/create_security_artifacts.sh -kdb2jks -sourcekdb 
   "${KEYFILES_DIR}"/default.server/keyfiles/keyfile.kdb  
   
   

   The ${KEYFILES_DIR}"/default.server/keyfiles/keyfile.jks" file is created. When you are finished you must remove the password from the environment: export -n APMPASS.
10. Convert the agent keystore from the GSKit format (*.kdb) to the Java keystore format (*.jks). You must set the agent keystore password:

    export APMPASS= "put_your_agent_keystore_password_here"
    /opt/ibm/ccm/create_security_artifacts.sh -kdb2jks -sourcekdb
    "${KEYFILES_DIR}"/default.agent/keyfiles/keyfile.kdb
    

    When you are finished, you must remove the password from the environment: export -n APMPASS.
11. If you did not set the KEYFILES_DIR directory to /opt/ibm/ccm/keyfiles, copy the created keyfiles to the main keyfiles directory.

    /bin/cp "${KEYFILES_DIR}"/default.agent/keyfiles/keyfile.* /opt/ibm/ccm/
    keyfiles/ 
        /bin/cp "${KEYFILES_DIR}"/default.agent/keyfiles/KAES256.ser /opt/ibm/ccm/
    keyfiles/
        /bin/cp "${KEYFILES_DIR}"/default.server/keyfiles/keyfile.jks /opt/ibm/ccm/
    keyfiles/server.jks
    

12. Copy the server keyfile.jks file to the security directory for the min service:

    /bin/cp  "${KEYFILES_DIR}"/default.server/keyfiles/keyfile.jks /opt/ibm/wlp/usr/ 
    servers/min/resources/security/key.jks

    If you previously added a CA certificate to the key.jks file to forward events using an SSL connection to your SMTP Server, you must re-add the CA certificate to the new keystore. For instructions, see Event Manager in Advanced Configuration.

13. Encode the (xor) server keystore password from step 4.

    /opt/ibm/wlp/bin/securityUtility encode

14. 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 if it does not already exist in the user-exit.xml file. (user-exit.xml is an override file for server.xml) Replace the password entry in user-exit.xml with the newly encoded password from step 13. Remove the keyStore xml element from the server.xml file.
15. Copy the ssl xml element that contains the enabledCiphers attribute from the install_dir/wlp/usr/servers/min/server.xml file to the install_dir/wlp/usr/servers/min/user-exit.xml file if it does not already exist in the user-exit.xml file. Then add this clientAuthentication="true" line after the enabledCiphers line in the user-exit.xml file. Remove the ssl xml element from the server.xml file.
16. Edit the values of the serverKeyAlias and clientKeyAlias attributes in the user-exit.xml file as shown to the values of the key labels specified in step 3 and step 4.

    serverKeyAlias="put_server_key_label_here" 
    clientKeyAlias="put_agent_key_label_here"

    Note: 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 "enabledCiphers="TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256" property.
17. Restart the min server:

    apm stop min
    apm start min

18. If the IBM® Cloud Application Performance Management Hybrid Gateway is installed in your Tivoli® Monitoring environment, copy the contents of the /opt/ibm/ccm/keyfiles/default.server/keyfile directory on your Cloud APM server to the /opt/ibm/wlp/usr/servers/hybridgateway/resources/security/ directory on the computer system where the Hybrid Gateway is installed and restart the Hybrid Gateway.
19. Complete one of the following steps depending on whether you have 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.
      • Modify the agent configuration file to show which certificate should be used by the agent. The following variable must be modified or added to the configuration file:

        KDEBE_KEY_LABEL="agent_key_label"

        For example, KDEBE_KEY_LABEL="APM_Agent_Certificate"

        • For Windows 64-bit installation, modify the variable in the \TMAITM6_x64\KPCENV file where PC is the agent product code.
        • For Windows 32-bit installation, modify the variable in the \TMAITM6\KPCENV file where PC is the agent product code.

        For example, for an agent that is installed to C:\IBM\APM, to modify the OS agent configuration on a 64-bit installation, you must change the following file: C:\IBM\APM\TMAITM6_x64\KNTENV.

        • On Linux/AIX, modify the variable in the following file: agent_installation_path/config/global.environment.
      • Before you install new agents, use the agent configuration tool to modify the agent images to contain the new certificates.
    • 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".

         • 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.
20. You must configure the Cloud APM server agents to use HTTPS and certificates. See Configuring the communications protocol for server agents for instructions.