Administration Guide › Custom Certificates

Custom Certificates

This section contains the following topics:

Implementing Custom Certificates

Add the Trusted Root Certificate to the Management CA User Activity Reporting Module Server

Add the Trusted Root Certificate to All Other CA User Activity Reporting Module Servers

Add the Certificate Common Name to an Access Policy

Deploy the New Certificates

Implement Custom Certificates on Active Agents

Implement Custom Certificates in OpenAPI

Implementing Custom Certificates

The installation process generates two certificates and places them in the /opt/CA/SharedComponents/iTechnology directory of the CA User Activity Reporting Module server. You can use the installed certificates as is. These certificates have the following names, where ApplicationName is CAELM for the CA User Activity Reporting Module product.

• ApplicationNameCert.cer

  This certificate is used by all CA User Activity Reporting Module services to communicate with the management server. The entry for this certificate also exists under the CALM.cnf file.

• ApplicationName_AgentCert.cer

  This certificate is used by all the Agents to communicate with the CA User Activity Reporting Module server.

To use custom certificates, you must first obtain a trusted root certificate from a Root Certificate Authority (CA). A certificate authority can issue multiple certificates in the form of a tree structure. All certificates below the trusted root certificate inherit the trustworthiness of the root certificate. This process assumes that if both certificates are being replaced, the custom service certificate and the custom agent certificate have the same trusted root.

After you obtain a trusted root certificate, the typical sequence of actions to implement custom certificates are as follows:

1. Add the Trusted Root certificate to iAuthority.conf on the management CA User Activity Reporting Module server or standalone CA EEM.
2. If you are replacing CAELM_AgentCert.cer, add the Trusted Root certificate to iControl.conf on the management CA User Activity Reporting Module, then repeat this addition on every other CA User Activity Reporting Module.
3. If you are replacing CAELMCert.cer, add this custom certificate's common name to the AdministerObjects scoping policy on the management CA User Activity Reporting Module or standalone CA EEM.
4. Add the custom certificates to the iTechnology folder of each CA User Activity Reporting Module server and add the name and password for each certificate in separate configuration files.

More information:

Agents and the Agent Certificate

Add the Trusted Root Certificate to the Management CA User Activity Reporting Module Server

First, you obtain a Trusted Root Certificate in PEM format from the Certifying Authority (CA). Then you add this Trusted Root Certificate into the iTechnology SPIN web interface of the management server or standalone CA EEM.

To add the Trusted Root Certificate to the management CA User Activity Reporting Module

1. Browse to the CA iTechnology SPIN web interface of the management CA User Activity Reporting Module server or the standalone CA EEM.

   https://<management_ELM_hostname>:5250/spin
   

   https://<EEM_hostname>:5250/spin
   

   The CA iTechnology SPIN page appears.

2. Select iTech Administrator from the drop-down list and click Go.

   The iTechnology Administrator page appears with a Login link.

3. Click Login.

   The CA iTechnology logon dialog appears.

4. Enter the EiamAdmin credentials and click Log In.
5. Select the iAuthority tab and add the Trusted Root to iAuthority.conf as follows:
   1. Enter a Label for the certificate. Do not enter "myself" as the label.
   2. Browse and select the .cer file.
   3. Click Add Trusted Root.

   The confirmation message indicates that the trust root is added to the iAuthority.conf, a file that exists only on the management server or on the standalone CA EEM.

6. If you are replacing the CAELM_AgentCert.cer certificate with a custom certificate, add the Trusted Root to iControl.conf as follows:
   1. Select the Configure tab.
   2. Enter the same Label for the certificate that you entered in the previous step.
   3. Browse and select the same root PEM (.cer) file that you selected in a previous step.
   4. Click Add Trusted Root.

   The confirmation message indicates that the trusted root of the custom certificate is added to the iControl.conf file in the iTechnology directory of the management CA User Activity Reporting Module server.

7. Click Logout and close the iTechnology SPIN.

Add the Trusted Root Certificate to All Other CA User Activity Reporting Module Servers

If you are replacing the CAELM_AgentCert.cer certificate with a custom certificate, you must add the Trusted Root Certificate into the iTechnology SPIN web interface of each additional CA User Activity Reporting Module server. In this procedure, you add the Trusted Root Certificate to CA iControl. This procedure is not needed if you are replacing only the CAELMCert.cer certificate.

To add the Trusted Root Certificate to CA iControl of each non-management CA User Activity Reporting Module server

1. Log into the SPIN UI on the iGateway where a non-management server is running. Use the following URL:

   https://<ELM_hostname>:5250/spin/
   

   The CA iTechnology SPIN page appears.

2. Select iTech Administrator from the drop-down list and click Go.

   The iTechnology Administrator page appears with a Login link.

3. Click Login.

   The CA iTechnology logon dialog appears.

4. Enter the EiamAdmin credentials and click Log In.
5. Select the iAuthority tab and add the Trusted Root to iAuthority.conf as follows:
   1. Enter a Label for the certificate. Do not enter "myself" as the label.
   2. Browse and select the .cer file.
   3. Click Add Trusted Root.
6. Select the Configure tab and add the Trusted Root as follows:
   1. Enter the same Label for the certificate that you entered in the previous step.
   2. Browse and select the same root PEM (.cer) file that you selected in a previous step.
   3. Click Add Trusted Root.

   The trusted root of the custom certificate is added to the iControl.conf file in the iTechnology directory. A confirmation message appears.

7. Click Logout and close the iTechnology SPIN.

Add the Certificate Common Name to an Access Policy

The CAELMCert.cer certificate is used by all CA User Activity Reporting Module services to communicate with the management CA User Activity Reporting Module server. If you replace CAELMCert.cer with a custom certificate, you must add this custom certificate's common name (cn) to the AdministerObjects policy on the management server or the standalone CA EEM server.

Note: It is not necessary to delete [User] CERT_CAELM identity, the common name of the default certificate, from this policy.

Follow these steps:

1. Browse to the management CA User Activity Reporting Module server or the standalone CA EEM server by entering the appropriate URL.

   https://<management_server_hostname>:5250/spin/calm
   

   https://<EEM_server_hostname>:5250/spin/eiam
   

2. Log in with Administrative privileges to the CA User Activity Reporting Module management server. If accessing a standalone CA EEM, log in as the EiamAdmin user.
3. Click the Administration tab, the User and Access Management subtab, and the Access Policy link in the left pane. If logged into a standalone CA EEM, click the Manage Access Policies tab.
4. Click the Scoping Policies link.

   The Policy Table of scoping policies appears in the main pane.

5. Scroll to the Administer Objects policy and select the AdministerObjects link.

   The AdministerObjects policy opens in edit mode.

6. Add the common name (cn) of the custom certificate as follows:
   1. Enter the common name of the custom certificate in the Identity field.
   2. Click the arrow to move your entry.

      [User}<custom certificate cn> appears in the Selected Identities list.

7. Click Save.

   The AdministerObjects policy is saved with the addition of the common name of your custom certificate as an identity granted read and write access to the resources listed in this policy.

8. Click Close and log out of the CA User Activity Reporting Module user interface.

Deploy the New Certificates

CA User Activity Reporting Module uses two certificates. You can replace them with custom certificates. To deploy new certificates, you log on to the soft appliance, stop iGateway, add the new certificates, modify the respective configuration files, and then restart iGateway.

Before you deploy new certificates, verify that:

• The Trusted Root Certificate has been added to the iTechnology iAuthority of the management server or standalone CA EEM your CA User Activity Reporting Module servers use.
• If you are replacing CAELM_AgentCert.cer with a custom certificate, the Trusted Root Certificate has been added to the iTechnology iControl of each CA User Activity Reporting Module server.
• The custom certificate's common name has been added to the AdministerObjects access policy. This refers to the custom certificate that is to replace CAELMCert.cer.
• If you are using the P12 certificates, all the agents in your environment are upgraded to CA User Activity Reporting Module 12.6 SP2 or later, and FIPS mode is set to off.

Follow these steps:

1. Access the host where the CA User Activity Reporting Module server is installed.
2. Use your caelmadmin credentials to log on to the CA User Activity Reporting Module server.
3. At the command prompt, switch users to root, that is:

   su - root
   

4. Change directories to /opt/CA/SharedComponents/iTechnology with the following shortcut:

   cd $IGW_LOC
   

5. Stop iGateway:

   ./S99igateway stop
   

6. To replace CAELMCert.cer:
   1. If you are using PEM certificate, copy the custom ApplicationNameCert.cer certificate and the ApplicationNameCert.key key file into the iTechnology directory.
   2. If you are using P12 certificate, perform the following steps to create the key file:
      1. Run the following command:

         ./safex -munge <P12_certificate_password>
         

         The munged password is displayed.

      2. Run the following command:

         echo -n <munged_password> > ApplicationNameCert.munge
         

      3. Copy the custom ApplicationNameCert.p12 certificate file into the iTechnology directory.
   3. Open the CALM.cnf file.
   4. Configure the <certType> tag with your certificate type, pem or p12.

      Default: pem

   5. Replace the existing certificate name with the new certificate name.
   6. Replace the existing key name with the new key name.
7. To replace CAELM_AgentCert.cer:
   1. If you are using PEM certificate, copy the custom ApplicationName_AgentCert.cer certificate and the ApplicationName_AgentCert.key key file into the iTechnology directory.
   2. If you are using P12 certificate, perform the following steps to create the key file:
      1. Run the following command:

         ./safex -munge <P12_certificate_password>
         

         The munged password is displayed.

      2. Run the following command:

         echo -n <munged_password> > ApplicationName_AgentCert.munge
         

      3. Copy the custom ApplicationName_AgentCert.p12 certificate file into the iTechnology directory.
   3. Open the AgentManager.conf file.
   4. Configure the <certType> tag with your certificate type, pem or p12.

      Default: pem

   5. Replace the existing certificate name with the new certificate name.
   6. Replace the existing key name with the new key name.
8. Start iGateway.

   ./S99igateway start
   

   All agents installed after this deployment automatically use the custom certificate.

Implement Custom Certificates on Active Agents

You can implement custom certificates on active agents without reinstalling the agents.

Follow these steps:

1. Navigate to the bin folder of the agent installation path.
2. Execute the following command:

   Windows

   agentconfig.exe -redirectagent -server <UARM server> -authcode <authentication key>
   

   UNIX

   ./agentconfig -redirectagent -server <UARM server> -authcode <authentication key>
   

3. (Windows) Restart the agent.
4. Verify that the agent sends events to the server.

Implement Custom Certificates in OpenAPI

Install custom certificates on CA User Activity Reporting Module server and run EEMImportUtility to implement custom certificates in OpenAPI. EEMImportUtility has the following syntax:

EEMImportUitlity.sh -h <Backend> -u "EiamAdmin" [-p <plain_pwd> | -m <munge_pwd>]  -a  <CAELM_App_instance_name> -type "openAPICustCert" -registerProduct -prodCertName <prod_name> -prodCertPwd <pwd> -prodCustCertName <CUST_CERT.cer|CUST_CERT.p12> -prodCustCertKey <CUST_CERT.key|CUST_CERT.munge>]

Backend

Defines the hostname of the CA User Activity Reporting Module server.

plain_pwd

Defines the EiamAdmin password in plain text. If you want to use a munged password, do not specify this value.

munge_pwd

Defines the munged password of the EiamAdmin password. If you want to use a plain password, do not specify this value. To generate a munged password, navigate to /opt/CA/LogManager/EEM/ and execute the following command:

./safex -munge <password>

CAELM_App_instance_name

Defines the name of the CA User Activity Reporting Module instance.

Default: CAELM

prod_name

Defines the product name that must be registered with OpenAPI.

pwd

Defines the password that must be associated with the product name that you defined.

CUST_CERT.cer|CUST_CERT.p12

Defines the custom certificate that you installed CA User Activity Reporting Module server.

CUST_CERT.key|CUST_CERT.munge

Defines the key of the custom certificate.

To register a product with OpenAPI, perform the following steps:

1. Navigate to /opt/CA/LogManager/EEM/content.
2. Execute the following command to run EEMImportUtility:

   ./EEMImportUitlity.sh -h <Backend> -u "EiamAdmin" [-p <plain_pwd>|-m <munge_pwd>] -a <CAELM_App_instance_name> -type "openAPICustCert" -registerProduct -prodCertName <prod_name> -prodCertPwd <pwd> -prodCustCertName <CUST_CERT.cer|CUST_CERT.p12> -prodCustCertKey <CUST_CERT.key|CUST_CERT.munge>]
   

To unregister a product with OpenAPI, perform the following steps:

1. Navigate to /opt/CA/LogManager/EEM/content.
2. Execute the following command to run EEMImportUtility:

   EEMImportUtility.sh -h <Backend> -u "EiamAdmin" [-p <plain_pwd> | -m <munge_pwd>]  -a  <CAELM_App_instance_name> -type "openAPICustCert" -unregisterProduct -prodCertName <prod_name>