How to Generate or Update the Encryption Key for Confidential Manager

You can generate or update an encryption key to be used for encryption or decryption of Confidential Manager communication and authentication configurations exchanged between the UCMDB Server and the Data Flow Probe. In each case (generate or update), the UCMDB Server creates a new encryption key based on parameters that you supply (for example, key length, extra PBE cycles, JCE provider) and distributes it to the Probes.

The result of running the generateEncryptionKey method is a new generated encryption key. This key is stored only in secured storage and its name and details are not known. If you reinstall an existing Data Flow Probe, or connect a new Probe to the UCMDB Server, this new generated key is not recognized by the new Probe. In these cases, it is preferable to use the changeEncryptionKey method to change encryption keys. This way, when you reinstall a Probe or install a new Probe, you can import the existing key (whose name and location you know) by running the importEncryptionKey method on the Probe JMX console.

This task includes the following steps:

• Generate a New Encryption Key
• Update an Encryption Key on a UCMDB Server
• Update an Encryption Key on a Probe
• Manually Change the Encryption Key when the Probe Manager and Probe Gateway are Installed on Separate Machines
• Define Several JCE Providers
  

Generate a New Encryption Key

You can generate a new key to be used by the UCMDB Server and Data Flow Probe for encryption or decryption. The UCMDB Server replaces the old key with the new generated key, and distributes this key among the Probes.

To generate a new encryption key through the JMX console:

1. On the UCMDB server, launch the Web browser and enter the following address: https://localhost:8443/jmx-console.

   You may have to log in with a user name and password.

2. Click UCMDB:service=DiscoveryManager to open the JMX MBEAN View page.

3. Locate the generateEncryptionKey operation.

   1. In the customerId parameter box, enter 1 (the default).

   2. For keySize, specify the length of the encryption key. Valid values are 128, 192, or 256.

   3. For usePBE, specify True or False:

      • True: use additional PBE hash cycles.

      • False: do not use additional PBE hash cycles.

   4. For jceVendor, you can choose to use a non-default JCE provider. If the box is empty, the default provider is used.

   5. For autoUpdateProbe, specify True or False:

      • True: the server distributes the new key to the Probes automatically.

      • False: the new key should be placed on the Probes manually.

   6. For exportEncryptionKey, specify True or False.

      • True: In addition to creating the new password and storing it in secured storage, the Server exports the new password to the file system (C:\UCMDB\UCMDBServer\conf\discovery\key.bin). This option enables you to update Probes manually with the new password.

      • False: The new password is not exported to the file system. To update Probes manually, set autoUpdateProbe to False and exportEncryptionKey to True.

      Caution Make sure that the Probe is up and connected to the server. If the Probe goes down, the key cannot reach the Probe. If you change the key before the Probe goes down, once the Probe is up again, the key is sent again to the Probe. However, if you have changed the key more than once before the Probe goes down, you must change the key manually through the JMX console. (Select False for exportEncryptionKey).

4. Click Invoke to generate the encryption key.

Update an Encryption Key on a UCMDB Server

You use the changeEncryptionKey method to import your own encryption key to the UCMDB server and distribute it among all Probes.

To update an encryption key through the JMX Console:

1. Copy the key.bin file you generated in Generate a New Encryption Key to the C:\UCMDB\UCMDBServer\conf\discovery\customer_1 directory, and rename the key.bin file. For example, key_1.bin.

   Note: Make sure you rename the key.bin file.

2. On the UCMDB Server, launch the Web browser and enter the following address: https://localhost:8443/jmx-console. You may have to log in with a user name and password.

3. Click UCMDB:service=DiscoveryManager to open the JMX MBEAN View page.

4. Locate the changeEncryptionKey operation.

   1. In the customerId parameter box, enter 1 (the default).

   2. For newKeyFileName, enter the name of the new key.

   3. For keySizeInBits, specify the length of the encryption key. Valid values are 128, 192, or 256.

   4. For usePBE, specify True or False:

      • True: use additional PBE hash cycles.

      • False: do not use additional PBE hash cycles.

   5. For jceVendor, you can choose to use a non-default JCE provider. If the box is empty, the default provider is used.

   6. For autoUpdateProbe, specify True or False:

      • True: the server distributes the new key to the Probes automatically.

      • False: the new key should be distributed manually using the Probe JMX console.

      Caution Make sure that the Probe is up and connected to the server. If the Probe goes down, the key cannot reach the Probe. If you change the key before the Probe goes down, once the Probe is up again, the key is sent again to the Probe. However, if you have changed the key more than once before the Probe goes down, you must change the key manually through the JMX console. (Select False for autoUpdateProbe).

5. Click Invoke to generate and update the encryption key.

Update an Encryption Key on a Probe

If you choose not to distribute an encryption key from the UCMDB Server to all Probes automatically (because of security concerns), you should download the new encryption key to all Probes and run the importEncryptionKey method on the Probe:

1. Place the encryption key file in C:\UCMDB\DataFlowProbe\conf\security\.

2. On the Probe machine, launch the Web browser and enter the following address: https://localhost:8453.

   You may have to log in with a user name and password.

   Note If the Probe Manager and the Probe Gateway are running as separate processes, the address should be entered on the machine that is running the Probe Manager as follows: https://localhost:8454.

3. On the Probe domain, click type=SecurityManagerService.
4. Locate the importEncryptionKey method.
5. Enter the name of the encryption key file that resides in C:\UCMDB\DataFlowProbe\conf\security\. This file contains the key to be imported.
6. Click the importEncryptionKey button.
7. Perform a restart of the probe.

Manually Change the Encryption Key when the Probe Manager and Probe Gateway are Installed on Separate Machines

1. On the Probe Manager machine, start the Probe Manager service (Start > All Programs > UCMDB > Start Data Flow Probe Manager).
2. Import the key from the server, using the Probe Manager JMX. For details, see Generate a New Encryption Key.
3. After the encryption key is imported successfully, restart the Probe Manager and Probe Gateway services.

Define Several JCE Providers

When you generate an encryption key through the JMX Console, you can define several JCE providers, using the changeEncryptionKey and generateEncryptionKey methods.

To change the default JCE provider:

1. Register the JCE provider jar files in $JRE_HOME/lib/ext.

2. Copy the jar files to the $JRE_HOME folder:

   • For the UCMDB Server: $JRE_HOME resides at: C:\UCMDB\UCMDBServer\bin\jre

   • For the Data Flow Probe: $JRE_HOME resides at: C:\UCMDB\DataFlowProbe\bin\jre

3. Add the provider class at the end of the provider list in the $JRE_HOME\lib\security\java.security file.
4. Update the local_policy.jar and US_export_policy.jar files to include unlimited JCE policies. You can download these jar files from the Sun website.
5. Restart the UCMDB Server and the Data Flow Probe.
6. Locate the JCE vendor field for the changeEncryptionKey or generateEncryptionKey method, and add the name of the JCE provider.