Implementing a CA Signed Certificate for Tomcat

  • 7021429
  • 17-Oct-2002
  • 02-Mar-2018

Environment

Reflection Security Gateway 2014
Reflection for the Web 2014 (All Editions)
Reflection for the Web 2011 (All Editions)
Reflection for the Web 2008 (All Editions)
Apache Tomcat version 4.0.1 or higher

Situation

This technical note provides instructions on how to request a signed certificate from a Certificate Authority (CA) and how to install the certificate after it is received.

Note: This technical note should be used only if you are using Apache (Jakarta) 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 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.

Resolution

What Kind of Certificate?

You will need a server certificate (also known as a web server certificate, a site certificate, or an SSL certificate) for the server on which Tomcat is installed. This enables clients to communicate with the Tomcat web server using HTTPS. If you are not using HTTPS, you do not need this certificate. If your organization already has a server certificate for the server on which Tomcat resides, or if you have an internal CA, you can bypass the process of registering with a Certificate Authority, and you may skip to the section on "Importing the Key Pair."

Note: For information about using an OpenSSL certificate with Reflection, see KB 7022218.

Selecting a Certificate Authority

Depending on the CA, the registration process can take a few weeks. The following are selected links to the web sites of well-known CAs. (You are not limited to using the CAs listed on this page, but you should select one that is included in your browser's list of CAs.)

Entrust Certificate Services: http://www.entrust.net
Thawte: http://www.thawte.com
VeriSign: http://www.verisign.com

Note: Entrust is not included in some Apple Macintosh's trusted certificate store.

Obtaining a Certificate from a Certificate Authority (CA)

Use one of two methods to obtain a certificate signed by a CA:

  • You generate the key pair. To do this you must generate a Certificate Signing Request (CSR). When you generate a CSR, a key pair is created. You keep the private key and ask the CA to sign the certificate. This method is more secure, because the private key never leaves your hands.
  • CA generates the key pair. You can choose not to generate a CSR and ask the CA to generate the key pair, sign the certificate, and send the key pair to you. This method is less secure (though very commonly used) because the CA sends you the private key.

You Generate the Key Pair

Use the utility provided in the Administrative WebStation to generate the Certificate Signing Request (CSR). This process generates a key pair. Follow these steps to generate a CSR:

  1. In the Administrative WebStation, go to Tools > Security Setup > Certificates tab > "Administer Certificate Signing Requests" section and click the link to "Generate a certificate signing request to a Certificate Authority."
  2. Complete the form with the requested information. Be sure the common name is the same server name that will be used in the URL when users launch a Reflection session. In many cases, this may need to be the fully qualified domain name of the web server.
  3. Click Submit. Notice that the form displays the location where the output file will be placed. In a default Windows installation, the location is

Reflection Security Gateway 2014, Reflection for the Web 2014, or Reflection for the Web 2011:

C:\ProgramData\Attachmate\ReflectionServer\ReflectionData\certificates

Reflection for the Web 2008:

C:\Program Files\ReflectionServer\ReflectionData\certificates
  1. Review the information on the confirmation page. Click Submit.

This returns you to the Certificates tab. Notice that there is now a link for "View and process pending certificate signing requests." If you choose, you can click this link to see the file name in which the CSR is stored. (This is the *.txt file you named while completing the form in Step 2.)

To send this information to the CA, locate the *.txt file in which the CSR is stored, open it in Notepad, and copy the entire contents of it, including the beginning and end lines, into the form that the CA supplies. In some cases, the CA may ask you to forward the file, instead.

The CA Sends You the Signed Certificate

The CA will send you a signed certificate, usually in the form of a *.cer or *.der file. Place the file in the folder used by Reflection to process certificate files. In a default Windows installation, the location is

Reflection Security Gateway 2014, Reflection for the Web 2014, or Reflection for the Web 2011:

C:\ProgramData\Attachmate\ReflectionServer\ReflectionData\certificates

Reflection for the Web 2008:

C:\Program Files\ReflectionServer\ReflectionData\certificates

Reflection can work with files in the Base64 and DER formats.

Implement the Signed Certificate on the AWS Certificates Tab

Implementing the signed certificate is a two-phase process. First, you must process the signed certificate on the Administrative WebStation (AWS) Certificates tab. This process creates a keystore (*.pfx) file that contains both the certificate you received from the CA and the private key that you generated when you created the CSR. Then, you must use the Certificate Wizard to import the certificate to Tomcat.

Note: In Reflection, the Certificate Wizard requires that Java 1.4.x or higher be installed. If you installed Reflection using the Windows automated installer, the correct Java version is automatically installed. If you installed Reflection manually, you must install the Java version required for your version of Reflection. Technical Note 1699 outlines the steps for installing the Java SDK.

Follow these steps to process the certificate for Tomcat on the AWS Certificates tab:

  1. Launch the Administrative WebStation.
  2. Go to Tools > Security Setup > Certificates tab > "Administer Certificate Signing Requests" section. Click the link for "View and process pending certificate signing requests."

On this page, you can view the list of pending requests. Reflection automatically matches up the certificate with the correct request.

  1. Click the link, "Process the signed certificate."
  2. Fill in the fields, and click Submit:
    • In the CA filename field, enter the name of the file that came back from the CA.
    • In the CA password field, enter the password (if any) that protects the file that was returned from the CA.
    • In the Keystore filename field, enter a name for the output file that will contain the key pair. This is the file that Reflection is about to generate. The filename should end with the .pfx extension.
    • In the Keystore password field, enter a password if you want to protect the keystore file.
    • Attachmate recommends that you do not select the "Install certificate" check box. Although it is possible, with this option, to use the CA signed certificate with the management server as well as with Tomcat, in most cases, it is more secure to continue to use the self-signed certificate for the management server.
  1. A confirmation screen tells you where the *.pfx file has been generated. In a default Windows installation, it is located in:
C:\ProgramData\Attachmate\ReflectionServer\ReflectionData\certificates

Follow these steps to import the key pair for Tomcat using the Certificate Wizard:

  1. Launch the Certificate Wizard.

In Windows, in Reflection Security Gateway 2014, Reflection for the Web 2014, or Reflection for the Web 2011 browse to \Program Files\Attachmate\ReflectionServer\utilities\bin directory and run the CertificateWizard.exe by right-clicking the file and selecting the option to "Run as administrator."

In Reflection for the Web 2008, click Start > Programs > Attachmate Reflection for the Web > Utilities > Certificate Wizard.

In UNIX, follow the steps below.

Note: This command must be run from the console or from a graphical user interface, such as Reflection X.

    1. Go to the directory where CertWizard.jar is located, typically in /usr/local/ReflectionServer/utilities.
    2. At the prompt, enter (all one line):

For Reflection Security Gateway 2014, Reflection for the Web 2014, or Reflection for the Web 2011:

java -cp /opt/attachmate/reflectionserver/utilities/lib/KeyTools
Pro_jce1-2-1_1of2_signed.jar:/opt/attachmate/reflectionserver/
utilities/lib/CertWizard.jar run

For Reflection for the Web 2008:

java -cp /usr/local/ReflectionServer/utilities/KeyTools
Pro_jce1-2-1_1of2_signed.jar:/usr/local/ReflectionServer/
utilities/CertWizard.jar run

Note: On some systems, you may need to remove "run" from the command.

  1. Click Next until you get to the screen that asks: "Generate, import, update, or copy?" Select "Import a new CA-signed certificate."

Note: Before you get the screen described above, you will be prompted to manually stop the Tomcat servlet runner. (To do this, you must stop Reflection Server from Windows Services.)

  1. Browse to the *.pfx file you generated above. Click Next.
  2. If the file is password protected, then enter the password and click Next. You should get a confirmation screen that the import succeeded. (The wizard will stop and restart the Tomcat service.)

The Tomcat self-signed certificate has now been replaced with a certificate signed by a Certificate Authority.

CA Generates the Key Pair

If you choose to use the second method for obtaining a certificate, you must contact the CA to generate the key pair. Please note that this method is not as secure as when you generate the CSR because the CA has to send you the private key.

The CA Sends You the Signed Certificate

The CA will send you a key pair (private key and signed certificate). Place the file in the folder used by Reflection to process certificate files. In a default Windows installation, the location is

Reflection Security Gateway 2014, Reflection for the Web 2014, or Reflection for the Web 2011:

C:\ProgramData\Attachmate\ReflectionServer\ReflectionData\certificates

Reflection for the Web 2008:

C:\Program Files\ReflectionServer\ReflectionData\certificates

Note the following:

  • Reflection works with *.pfx files. If you need assistance importing files with a different extension, contact Technical Support. For contact information, see https://support.microfocus.com/contact/.
  • For information about using an OpenSSL certificate with Reflection, see KB 7022218.

Importing the Key Pair

Follow the steps below to import the key pair (certificate and private key) generated by the CA.

  1. Launch the Certificate Wizard.

In Reflection Security Gateway 2014, Reflection for the Web 2014, or Reflection for the Web 2011, browse to \Program Files\Attachmate\ReflectionServer\utilities\bin directory and run the CertificateWizard.exe by right-clicking the file and selecting the option to "Run as administrator."

In Reflection for the Web 2008, click Start > Programs > Attachmate Reflection for the Web > Utilities > Certificate Wizard.

  1. Click Next until you get to the screen that asks: "Generate, import, update or copy?" Select "Import a new CA-signed certificate."
  2. Browse to the key pair sent by the CA. Click Next.
  3. If the file is password protected, then enter the password and click Next. You should get a confirmation screen that the import succeeded. (The wizard will stop and restart the Tomcat service.)

The Tomcat self-signed certificate has now been replaced with a certificate signed by a Certificate Authority.

Testing the New Certificate

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

  1. Use your browser to connect to the Reflection 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.

Troubleshooting

This section describes some common mistakes you may encounter when implementing a signed certificate.

After generating a CSR, trying to import a CA file as a key pair

A common mistake is to send a CSR to the CA, get a file back in response, and then try to import that file as a key pair.

If this happens in the Certificate Wizard (for importing the Tomcat Certificate), you get this error message:

An error occurred while importing the certificate:
Failed to open the keystore C:\Program Files\Attachmate\
ReflectionServer\ReflectionDate\Certificates\<filename>

When using the CSR method to obtain a certificate, you must process the signed certificate in the Administrative WebStation. This step matches the private key that Reflection for the Web stored with the certificate that came back from the CA. If you forget this step, then your attempt to import the key pair will fail, because the *.cer (or *.der) file you are attempting to import does not contain a key pair. It is lacking the private key.

To avoid this error, make sure you follow all the steps described in the You Generate the Key Pair section.

CA sends the wrong certificate

Another common mistake is to get the wrong kind of certificate from the CA. For example, if you get a Code Signing Certificate, and then try to install it as a Server Certificate, it won't work. Code signing certificate files sometimes have a *.spc extension.

Find the correct certificate

Sometimes when you order a certificate from a CA, they will send you a number of files with different types of certificates in them. You may have to sort through the files to find the right one. Typically, the CA will enclose documentation explaining what has been sent to you. A *.cer or *.der file usually contains a server certificate.

Additional Information

Legacy KB ID

This document was originally published as Attachmate Technical Note 1702.

Feedback service temporarily unavailable. For content questions or problems, please contact Support.