Configuring a self-signed certificate

You might want to use your own certificate instead of the certificate that is generated by the (CA) certificate authority or the default cert that is generated by the 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 server machine and to the KEYFILES_DIR that is set to the /opt/ibm/ccm/keystore directory.
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 hostname with a user-defined hostname.

   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 hostname. 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 the host name to -hostname option. It might be a generic host name or a real host name of the server. You must set the password for the server keystore and the private key:

   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 MIN 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. 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.jks file to the Liberty server location. To ensure secure agent communication, use the min server:

    /bin/cp /opt/ibm/ccm/keyfiles/server.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:

    /opt/ibm/wlp/bin/securityUtility encode

14. Replace the password entry in the server configuration with the newly encoded password from step 12. Open the /opt/ibm/wlp/usr/servers/min/server.xml file in a text editor. Find the line that contains the "defaultKeyStore" definition of the keystore and replace the password entry.
15. If you changed key labels in steps 3 and 4 (from an argument to a -label option), you need to edit the following properties in the /opt/ibm/wlp/usr/servers/min/server.xml:

    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 server.xml then you must add the entries to the <ssl> section after the "enabledCiphers="TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256" property.
16. Restart the min server:

    apm stop min
    apm start min

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

    cp /opt/ibm/ccm/keyfiles/keyfile.* /opt/ibm/wlp/usr/servers
    /hybridgateway/resources/security/

18. Select one of the following steps:
    • If you installed agents, then copy the keystore files to the agent installation directory: cp "/opt/ibm/ccm/keyfiles/keyfile.* path_to_agent_images/keyfiles.".
      • 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.
        • For Windows 32-bit installation, modify the variable in the \TMAITM6\KPCENV file.
        Note: You must replace PC with the valid 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.
      • Restart the agents.
    • If you did not install agents, use the agent pre-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.
      2. To pre-configure the agent images, use the /opt/ibm/ccm/configure_agent_images script.
      3. 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.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.

      The agent configuration package that you create by using the make_configuration_packages.sh script also contain the Windows package with the pre-configuration data and the Windows script.