Using Java Keytool to Obtain a CA Certificate and How to Install the Certificate to Tomcat

  • 7022204
  • 09-Jul-2013
  • 18-Mar-2018

Environment

Reflection for the Web (All Editions) version 12.3
Host Access Management and Security Server version 12.3
Reflection for the Web 2014 (All Editions)
Reflection for the Web 2011 (All Editions)
Reflection Security Gateway 2014

Situation

This technical note describes how use the Java keytool.exe command line utility to request a signed certificate from a Certificate Authority (CA) and how to install that certificate to Apache Tomcat after it is received.

Note: This technical note should be used only if you are using Apache Tomcat as your web server for Reflection for the Web or Reflection Security Gateway (hereinafter referred to as Reflection). (If you accept the defaults in a Reflection automated installation, Apache Tomcat is installed as your web server.)

If you have integrated Tomcat into Microsoft IIS, or if you are using a different web server, these steps do not apply. Instead, follow the documentation that is provided with your web server on how to import a CA signed certificate.

The procedure for doing this varies depending on the version of Reflection for the Web or MSS. Verify which version is being used, then follow the appropriate steps below.

Resolution

Reflection for the Web 12.3 or Management and Security Server 12.3

Step 1: Create a Keystore File and Generate a Key Pair

Using the Java keytool command line utility, the first thing you need to do is create a keystore file and generate the key pair.

Note: Reflection Web installs a copy of Java as it is needed for Apache Tomcat to run. You can use the keytool.exe command line utility that is included with it for this process. It is located in the following directory:

Windows:C:\Program Files\Micro Focus\MSS\jre\bin

UNIX:/opt/microfocus/mss/jre/bin

(Your directory structure may be different depending on where you installed MSS/RWeb.)

Follow the steps below based on your operating system:

For Windows:

  1. On the Windows Server, right-click the Command Prompt and select the option “Run as Administrator” or you will not be able to create the new keystore file.
  2. Change to the C:\Program Files\Micro Focus\MSS\jre\bin folder.
  3. Run the keytool.exe utility with the options as shown:

Proceed to Enter Your Information.

For UNIX:

  1. Open a terminal window and go to the directory:
/opt/microfocus/mss/jre/bin directory
  1. From the terminal window run the keytool utility with the options as shown:
./keytool -genkeypair -keysize 2048 -keyalg RSA -alias servlet-engine -storetype jceks -keystore servletcontainer.jks

Note: If you want to use a Subject Alternative Name (SAN) in your certificate, the following options can be added to the keytool command line.

If you are adding another name: –ext san=dns:servername.example.com

If you want to use an IP address: –ext san=ip:192.168.10.1

For example:

keytool -genkeypair -keysize 2048 -keyalg RSA -alias servlet-engine -storetype jceks –keystore servletcontainer.jks -ext san=dns:servername.example.com

Enter Your Information

When you run the keytool utility, you will be prompted to provide information. Before you respond to the prompts, note the following:

  • If you are writing the new keystore file to a directory other than a User directory, you may need Administrator privileges for the Command window or root privileges for the terminal.
  • We recommend that you use “not-secure” as the keystore password because it is the password that the MSS/RWeb installation of Tomcat uses. If you use a different password, it must also be changed in the server.xml file so that Tomcat can read the keystore. The same is true for the –alias option; you must use servlet-engine or the Reflection installation of Tomcat will not be able to read the keystore file.
  • For the prompt, What is your first and last name? enter the fully qualified domain name for the MSS/RWeb server, for example, rweb-server.microfocus.com.
  • For the prompt, Enter key password for <[servlet-engine]>, simply press the Enter key to use not-secure as your password.

The following graphic shows the prompts that are displayed by the keytool utility, with sample responses provided for illustrative purposes. When you run the keytool utility, enter responses that are appropriate for your environment.

View Full Size
Figure 1: Keytool Utility PromptsFigure 1: Keytool Utility Prompts

Make a backup copy of the keystore (servletcontainer.jks) file and store it in a safe place.

Step 2: Generate a Certificate Signing Request (CSR) Using the Newly Created Keystore

  1. Run the keytool utility with the options as shown below

Windows:keytool -certreq -alias servlet-engine -keyalg RSA -storetype jceks -file certreq.csr -keystore servletcontainer.jks

UNIX:./keytool -certreq -alias servlet-engine -keyalg RSA -storetype jceks -file certreq.csr -keystore servletcontainer.jks

  1. Enter keystore password (from Step 1), not-secure
  2. The CSR will be saved to the following directory:

Windows: C:\Program Files\Micro Focus\MSS\jre\bin

UNIX:/opt/microfocus/mss/jre/bin

  1. Submit the CSR to your Certificate Authority.

We recommend that you save the CSR in a safe place in case you need it for renewal or to request another certificate.

Step 3: Import the New CA-signed Certificate into the Keystore

Once you've obtained the CA-signed certificate from your Certificate Authority, follow these steps:

  1. Download your new certificate in PKCS#7 format. Most Certificate Authorities now send a file that contains the chained certificates, (which includes your signed certificate, the intermediate CA certificate, and the root CA certificate), in a certnew.p7b file.

If the newly signed certificate and intermediate CA certificates are received in email, you may need to copy and paste them into Notepad and save them as a cert.p7b. If you are using notepad.exe you may have to remove the .txt file extension once the file is saved.

  1. Import the certificate into the Java keystore by using the keytool utility with the options as shown:

Windows:keytool -import -alias servlet-engine -trustcacerts -storetype jceks -file cert.p7b -keystore servletcontainer.jks

UNIX:./keytool -import -alias servlet-engine -trustcacerts -storetype jceks -file cert.p7b -keystore servletcontainer.jks

Importing Certificates in a Chain Separately

If you do not receive your newly-signed certificate in the PKCS#7/file-name.p7b format, you may have to import the certificates in the chain one at a time, (which includes your signed certificate, the intermediate CA certificate, and the root CA certificate). The certificates must be imported in the proper order or the keytool certificate validation process will fail.

  1. Import the root CA certificate first:
keytool -import -alias root -trustcacerts -storetype jceks -file root.cer -keystore servletcontainer.jks
  1. Import the intermediate CA certificate second:
keytool -import -alias intermediate -trustcacerts -storetype jceks -file Intermediate.cer -keystore servletcontainer.jks
  1. Import your new CA signed certificate last:
keytool -import -alias servlet-engine -trustcacerts -storetype jceks -file new-cert.cer -keystore servletcontainer.jks

Step 4: Replace the Old Keystore in Apache Tomcat

Once the new cert is imported you can replace the existing keystore file that is being used by Tomcat.

  1. Rename the existing servletcontainer.jks file to servletcontainer.old. It will be located in the following directory:

Windows:C:\Program Files\Micro Focus\MSS\server\etc

UNIX:/opt/microfocus/mss/server/etc

  1. Copy the new keystore file into the following directory:

Windows:C:\Program Files\Micro Focus\MSS\server\etc

UNIX:/opt/microfocus/mss/server/etc

  1. Stop and Start the Micro Focus MSS Server for the change to take effect:

Windows: In the Windows Administrative Tools > Services utility, Stop and Start the Micro Focus MSS Server service.

UNIX: In the terminal window from the /opt/microfocus/mss/server/bin directory run ./server stop and then ./server start.

Step 5: Test the New Certificate

To test that the new certificate is being used, follow these steps:

  1. Use your browser to connect to the Reflection for the Web login or Links List page over HTTPS. You should no longer see the untrusted certificate warning from the browser.
  2. After you connect, double-click the lock icon in the browser's status bar and you should see the new certificate.

Reflection for the Web 12.2 or Management and Security Server 12.2 or earlier

Step 1: Create a Keystore File and Generate a Key Pair

Using the Java keytool command line utility, the first thing you need to do is create a keystore file and generate the key pair.

Note: Reflection Web installs a copy of Java as it is needed for Apache Tomcat to run. You can use the keytool.exe command line utility that is included with it for this process. It is located in the directory:

Windows:C:\Program Files\Attachmate\ReflectionServer\jre\bin

UNIX:/opt/Attachmate/ReflectionServer/jre/bin

(Your directory structure may be different depending on where you installed Reflection.)

Follow the steps below based on your operating system:

For Windows:

  1. On the Windows Server, right-click the Command Prompt and select the option “Run as Administrator” or you will not be able to create the new keystore file.
  2. Change to the C:\Program Files\Attachmate\ReflectionServer\jre\bin folder.
  3. Run the keytool.exe utility with the options as shown:
keytool -genkeypair -keysize 2048 -keyalg RSA -alias tomcat –keystore keystore

Proceed to Enter Your Information.

For UNIX:

  1. Open a terminal window and go to the directory:
opt/attachmate/reflectionserver/jre/bin directory
  1. From the terminal window run the keytool utility with the options as shown:
./keytool -genkeypair -keysize 2048 -keyalg RSA -alias tomcat –keystore keystore

Note: If you want to use a Subject Alternative Name (SAN) in your certificate, the following options can be added to the keytool command line.

If you are adding another name: –ext san=dns:servername.example.com

If you want to use an IP address: –ext san=ip:192.168.10.1

For example:

keytool -genkeypair -keysize 2048 -keyalg RSA -alias tomcat -keystore keystore -ext san=dns:servername.example.com

Enter Your Information

When you run the keytool utility, you will be prompted to provide information. Before you respond to the prompts, note the following:

  • If you are writing the new keystore file to a directory other than a User directory, you may need Administrator privileges for the Command window or root privileges for the terminal.
  • We recommend that you use changeit as the keystore password because it is the password that the Reflection installation of Tomcat uses. If you use a different password, it must also be changed in the server.xml file so that Tomcat can read the keystore. The same is true for the –alias option; you must use tomcat or the Reflection installation of Tomcat will not be able to read the keystore file.
  • For the prompt, What is your first and last name? enter the fully qualified domain name for the Reflection server, for example, rweb-server.attachmate.com.
  • For the prompt, Enter key password for <[tomcat]>, simply press the Enter key to use changeit as your password.

The following graphic shows the prompts that are displayed by the keytool utility, with sample responses provided for illustrative purposes. When you run the keytool utility, enter responses that are appropriate for your environment.

View Full Size
Figure 2: Keytool Utility PromptsFigure 2: Keytool Utility Prompts

Make a backup copy of the keystore file and store it in a safe place.

Step 2: Generate a Certificate Signing Request (CSR) Using the Newly Created Keystore

  1. Run the keytool utility with the options as shown below

Windows:keytool -certreq -alias tomcat -keyalg RSA -file certreq.csr -keystore keystore

UNIX:./keytool -certreq -alias tomcat -keyalg RSA -file certreq.csr -keystore keystore

  1. Enter keystore password (from Step 1), changeit
  2. The CSR will be saved to the following directory:

Windows: \jre\bin

UNIX:/opt/attachmate/reflectionserver /jre/bin

  1. Submit the CSR to your Certificate Authority.

We recommend that you save the CSR in a safe place in case you need it for renewal or to request another certificate.

Step 3: Import the New CA-signed Certificate into the Keystore

Once you've obtained the CA-signed certificate from your Certificate Authority, follow these steps:

  1. Download your new certificate in PKCS#7 format. Most Certificate Authorities now send a file that contains the chained certificates, (which includes your signed certificate, the intermediate CA certificate, and the root CA certificate), in a certnew.p7b file.

If the newly signed certificate and intermediate CA certificates are received in email, you may need to copy and paste them into Notepad and save them as a cert.p7b. If you are using notepad.exe you may have to remove the .txt file extension once the file is saved.

  1. Import the certificate into the Java keystore by using the keytool utility with the options as shown:

Windows:keytool -import -alias tomcat -trustcacerts -file cert.p7b -keystore keystore

UNIX:./keytool -import -alias tomcat -trustcacerts -file cert.p7b -keystore keystore

Importing Certificates in a Chain Separately

If you do not receive your newly-signed certificate in the PKCS#7/file-name.p7b format, you may have to import the certificates in the chain one at a time, (which includes your signed certificate, the intermediate CA certificate, and the root CA certificate). The certificates must be imported in the proper order or the keytool certificate validation process will fail.

  1. Import the root CA certificate first:
keytool -import -alias root -trustcacerts -file root.cer -keystore keystore
  1. Import the intermediate CA certificate second:
keytool -import -alias intermediate -trustcacerts -file Intermediate.cer -keystore keystore
  1. Import your new CA signed certificate last:
keytool -import -alias tomcat -trustcacerts -file new-cert.cer -keystore keystore

Step 4: Replace the Old Keystore in Apache Tomcat

Once the new cert is imported you can replace the existing keystore file that is being used by Tomcat.

  1. Rename the existing keystore file to keystore.old. It will be located in the following directory:

Windows:C:\Program Files\Attachmate\reflectionserver\apache-tomcat\conf

UNIX:/opt/attachmate/reflectionserver/apache-tomcat/conf

  1. Copy the new keystore file into the following directory:

Windows:C:\Program Files\Attachmate\reflectionserver\apache-tomcat\conf

UNIX:/opt/attachmate/reflectionserver/apache-tomcat/conf

  1. Stop and Start the Attachmate Reflection Server for the change to take effect:

Windows: In the Windows Administrative Tools > Services utility, Stop and Start the Attachmate Reflection Server service.

UNIX: In the terminal window from the /opt/attachmate/reflectionserver directory run ./ReflectionServer stop and then ./ReflectionServer start.

Step 5: Test the New Certificate

To test that the new certificate is being used, follow these steps:

  1. Use your browser to connect to the Reflection for the Web login or Links List page over HTTPS. You should no longer see the untrusted certificate warning from the browser.
  2. After you connect, double-click the lock icon in the browser's status bar and you should see the new certificate.

Additional Information

Legacy KB ID

This article was originally published as Attachmate Technical Note 2680.