Technical Notes

Implementing a CA Signed Certificate for Tomcat
Technical Note 1702
Last Reviewed 20-Apr-2007
Applies To
Reflection for the Web 2008 (All Editions)
Reflection for the Web version 8.0 through 9.x
Jakarta Tomcat Web Server version 4.01 or higher
Summary

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 Jakarta Tomcat as your web server for Reflection for the Web. (If you accept the defaults in a Reflection for the Web automated installation, Jakarta 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.

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 for the Web, see Technical Note 1864.

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.)

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 for the Web 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

4. Review the information on the confirmation page. Click Submit.

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 for the Web to process certificate files. In a default Windows installation, the location is

Reflection for the Web 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 for the Web, the Certificate Wizard requires that Java 1.4.x or higher be installed. If you installed Reflection for the Web using the Windows automated installer, the correct Java version is automatically installed. If you installed Reflection for the Web 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."

3. Click the link, "Process the signed certificate."
4. 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 for the Web 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.

5. A confirmation screen tells you where the *.pfx file has been generated. In a default Windows installation, it is located in:

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

1. Launch the Certificate Wizard.

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

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

3. Browse to the *.pfx file you generated above. Click Next.
4. 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 for the Web to process certificate files. In a default Windows installation, the location is

Note the following:

• Reflection for the Web works with *.pfx files. If you need assistance importing files with a different extension, contact Technical Support. For contact information, see http://support.attachmate.com/contact/.
• For information about using an OpenSSL certificate with Reflection for the Web, see Technical Note 1864.

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 Windows, click Start > Programs > Attachmate (or WRQ) Reflection for the Web > Utilities.)
2. Click Next until you get to the screen that asks: "Generate, import, update or copy?" Select "Import a new CA-signed certificate."
3. Browse to the key pair sent by the CA. Click Next.
4. 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 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.

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:

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.

Related Technical Notes

1699	Installing Reflection for the Web on UNIX or Linux
1704	Security Updates and Reflection for the Web
1864	Using an OpenSSL Certificate with Reflection for the Web