Setting up the keystore

To monitor HTTPS transactions, import keys into the KT5Keystore for all web servers that you want to monitor.

About this task

You can either export the SSL certificates from the web servers that you are monitoring and import them into the HTTPS Keystore by using IBM Key Management (iKeyman), or specify the web server's keystore stash file (.kdb) in the HTTPS Keystore. When you install or configure Response Time Monitoring, you are prompted for the location of the keys.kdb file.

If you do not have keystore stash files (.kdb and .sth), check that the CMS Provider is enabled in your Java version so that you can use iKeyman to set up the key database:

Go to the install_dir/ibm-jre/jre/lib/security directory. For example:
- /opt/ibm/apm/agent/JRE/lx8266/lib/security
- C:\Program Files\IBM\APM\ibm-jre\jre\lib\security

In the java.security file, add the following statement to the list of security providers as shown, where number is the last sequence number in the list.

security.provider.number=com.ibm.security.cmskeystore.CMSProvider

The list of providers looks like the following example:

## List of providers and their preference orders #
security.provider.1=com.ibm.jsse.IBMJSSEProvider
security.provider.2=com.ibm.crypto.provider.IBMJCE
security.provider.3=com.ibm.security.jgss.IBMJGSSProvider
security.provider.4=com.ibm.security.cert.IBMCertPath
security.provider.5=com.ibm.security.cmskeystore.CMSProvider
...
#

Save and close the file.

Restriction: Response Time Monitoring cannot decrypt traffic by using Diffie-Hellman key exchange.

Procedure

To enable HTTPS transaction monitoring, collect the SSL certificates from the web servers that you want to monitor and import the certificates and keystore stash files into the HTTPS Keystore by using iKeyman. The following example uses iKeyman to export the certificates from an IBM HTTP Server, and import them to HTTPS Keystore:

Install a Response Time Monitoring agent on each HTTPS web server that you want to monitor.
Run IBM Key Management (iKeyman) from within the IBM Java bin directory by running one of the following commands, depending on your operating system.
- /opt/ibm/apm/agent/JRE/lx8266/bin/ikeyman
  Note: You must have X-Window on the environment for iKeyman to work properly.
- c:\IBM\APM\java\java80_x64\jre\bin\ikeyman
Create a new Keystore database. In the New dialog box, complete the following steps:
1. From the Key database type list, select CMS.
  If CMS is not available in the list, the CMS Provider might not be enabled. Enable the CMS Provider in the Java security file.
2. In the File Name field, enter the name of the HTTPS Keystore file and click OK.
  For example, keys.kdb.
In the Password Prompt dialog box, complete the following steps:
1. In the Password and Confirm Password fields, enter and confirm the password to access keys.kdb.
  Do not set an expiration time unless you want to re-create the keystore database and restart the Response Time Monitoring agent periodically.
2. Select Stash the password to a file? to store the password for keys.kdb in an encrypted form in a stash file, keys.sth.
  Note: The Response Time agent supports stashed password version 1 only. After APM 8.1.4, run following command to store the password for keys.kdb in an encrypted stash file, keys.sth.
  On Linux:
```
cp keyfile.sth keyfile.sth.new-format
```
```
cd /opt/IBM/ccm/agent/lx8266/gs/bin
```
```
#export LD_LIBRARY_PATH=/opt/ibm/apm/agent/lx8266/gs/lib64:$LD_LIBRARY_PATH
```
```
./gsk8capicmd_64 -keydb -stashpw -db /opt/IBM/ccm/agent/keyfiles/keyfile.kdb -v1stash
```
  On Windows:
```
copy server.sth server.sth.backup
```
```
set PATH=c:\IBM\APM\GSK8_x64\lib64;%PATH%
```
```
C:\IBM\APM\GSK8_x64\bin\gsk8capicmd_64 -keydb -stashpw -db .\server.kdb -pw passw0rd -v1stash
```
In the Key database content section of the iKeyman window, complete the following steps:
1. Select Personal Certificates.
2. Click Import.
3. In the Import Key dialog box, from the Keyfile type list, select CMS.
4. Browse to the keystore file and click Open, and then click OK.
5. In the Password Prompt dialog box, enter the keystore password.
6. Select the key from the list and click OK.
7. In the Change Labels dialog box, select the key label name. In the Enter a new label field, specify the host name of the server and click Apply.
  
  Note: You will need this value when you configure Response Time Monitoring, so make a note of it.
8. Click OK.
Save the HTTPS Keystore.

Importing keys from Internet Information Services

To extract keys from Internet Information Services and import them into the KT5Keystore, complete the following steps:

Install a Response Time Monitoring agent on each HTTPS web server that you want to monitor.
Export a .pfx file from Internet Information Services:
1. From the Windows Start menu, select Administrative Tools > Internet Information Services (IIS) Manager.
2. Select the web server and site whose private key you want to export, then right-click and select Properties from the context menu.
3. Select the Directory Security tab, then select Server Certificate in the Secure communications section.
4. In the IIS Certificate Wizard, click Next.
5. Select Export the current certificate to a .pfx file and click Next.
6. Enter the path and file name and click Next.
7. Enter an export password for the key and click Next.
8. Click Next on all subsequent pages, then click Finish.
Extract Personal and Signer Certificates from the .pfx file:
1. Run IBM Key Management (iKeyman) from within the IBM Java bin directory using the command c:\IBM\APM\java\java80_x64\jre\bin\ikeyman. Ensure that the environment variable JAVA_HOME is set.
2. In the Keystore database, select File > Open.
3. From the Key database type list, select PKCS12.
4. Enter the name and path for the .pfx file you created above, then click OK. When prompted, enter the password, then click OK.
5. Select Key Database Content > Personal Certificates, then click Export/Import.
6. Select an Action Type of Export Key and a Key File Type of PKCS12. Enter a file name and location for the exported key and click OK. When prompted, enter an export password, then click OK again.
7. If the Personal Certificate was signed by a Certificate Authority, select Key Database Content > Signer Certificates and click Extract. Select the default file type, and enter a file name and location for the exported certificate, then click OK.
Extract Signer .cer files (if needed):
1. If a Signer Certificates file was extracted from the .pfx file, navigate to the directory where it was saved, and make a new copy with the extension .cer. Double-click the new copy to open it using the Windows Certificate viewer.
2. On the Certification Path tab, you can view the signer certificate chain. The lowest item in the chain should be the Personal Certificate. For all certificates above it, do the following:
  1. Select a certificate and click View Certificate.
  2. Select Details and click Copy to File.
  3. Accept all defaults in the Certificate Export Wizard and enter a filename with the .cer extension.
Create a new Keystore database. In the New dialog box, complete the following steps:
1. From the Key database type list, select CMS, and enter a filename and location. When prompted, enter a password for the new keystore.
  Note: Ensure you select Stash the password to a file.
2. If Signer Certificates were extracted from the .pfx file, do the following:
  1. Select Key Database Content > Signer Certificates.
  2. For each signer certificate, click Add and add the .cer file.
3. Select Key Database Content > Personal Certificates and click Import.
4. Select the key file type PKCS12, and the name and location of the .p12 file. When prompted, enter the password.
5. Save the keystore and exit the key management utility.
6. Copy the .kdb and .sth files to the KT5Keystore on the Response Time Monitoring appliance machine.
7. Place the IBM Key Management database files (.kdb) and stash (.sth) in a safe directory, and ensure that they are only readable by Administrator or root (or the user ID that was used to install the Response Time Monitoring agent).