Customizing SSL in CA WCC r11.3 This document contains guidelines for customizing SSL access to CA Workload Control Center (CA WCC) r11.3.

(1)

Customizing SSL in CA WCC r11.3

This document contains guidelines for customizing SSL access to CA Workload Control Center (CA WCC) r11.3.

Overview

This document shows how to configure a custom SSL Certificate for CA WCC’s Tomcat instances. In addition, the steps for changing WCC ‘server name to match a SSL certificate are explained. Note: The procedures in this document are for reference only; you may need to adjust them according to your needs and specifications. Important! The installation of CA WCC on which this procedure is being performed must have had the Enable SSL option selected during installation.

Conventions Used in This Document

The following conventions are used in this document: • $CA_WCC_INSTALL_LOCATION is the root directory of the CA WCC installation (typically, /opt/CA/WorkloadCC on Unix or c:\Program Files\CA\Workload Control Center on Windows). • The pound character (#) denotes the UNIX shell command prompt for the root user on UNIX, and a normal command prompt on Windows. This character should not be typed, • The backslash character (\) at the end of a line indicates that the command continues on the next line. On Windows, this character should not be typed. On Unix it can be typed provided it is followed immediately by a newline. • C.A. stands for Certificate Authority.

Changing the Certificate

There are three methods of changing the certificate: • Generate a self‐signed certificate—This is the easiest method. Users will need to acknowledge your certificate the first time they use it. • Generate a secret key and request a certificate—The keystore will generate a secret key and a certificate request. You need to submit your request to the C.A. (Certificate Authority) of your choice, which will in turn issue a certificate for you. • Import an existing private key and certificate—Use this method if you already have a private key and a matching certificate that you want to reuse.

(2)

Note: After changing the certificate using any of the methods above, you will need to restart the CA services.

Prerequisites

If you want to generate a self‐signed certificate, no additional software needs to be installed. For the other two methods of changing the certificate (Generate a secret key and request a certificate, and Import an existing private key and certificate), OpenSSL must be installed on the CA WCC server before you perform either of those procedures. The OpenSSL version used in this document is 0.98.

Install OpenSSL on Windows

OpenSSL for Windows is available from the following URL:

http://www.openssl.org/related/binaries.html

Note: The recommended version is ‘OpenSSL v0.9.8r Light’ . You might have to install first the ‘Visual C++ 2008 Redistributables’, also available from the same URL.

Edit the Path Environmental Variable

After you install OpenSSL, edit the Path environmental variable: 1. Click Start, Run, enter the following command, and click OK: SYSDM.CPL The System Properties dialog opens. 2. Go to Advanced, Environment Variables, System variables, select the Path variable, and click Edit. 3. Add the following text at the end of the Path environment variable: ;C:\OpenSSL\bin 4. Click OK to close each dialog that appears.

OpenSSL on UNIX

OpenSSL for UNIX can be obtained through your distribution’s repository. For example, on debian based distributions, simply type:

# apt-get install openssl

On rpm based distributions, simply type:

(3)

Generate a Self-signed Certificate

The first method of changing the certificate is to generate a self‐signed certificate. The steps are as follows:

1. Remove the previous key with the following command:

# $CA_WCC_INSTALL_LOCATION/jre/bin/keytool -delete -alias tomcat \

-keystore $CA_WCC_INSTALL_LOCATION/config/.keystore -storepass changeit

Note: The default name of the key is tomcat. To access the keystore, you also need the keystore password which by default is changeit.

2. Generate a new key with the following command:

# $CA_WCC_INSTALL_LOCATION/jre/bin/keytool -genkey -alias tomcat -keyalg RSA \ –keystore $CA_WCC_INSTALL_LOCATION/config/.keystore -storepass changeit \ -keypass changeit \

-keysize 1024 -dname "cn=WCC_SERVER_NAME" -validity 14600

In the command above: • Replace WCC_SERVER_NAME with the name of the CA WCC server that was specified during the installation of CA WCC. • The keysize argument lets you specify the key size. Typical values are 1024 or 2048. • The validity argument lets you specify how long the certificate should be valid (expressed in days). 3. Restart the CA WCC services. On Unix, use the following commands: # cd $CA_WCC_INSTALL_LOCATION/bin # ./StopWCCServices.sh # ./StartWCCServices.sh On Windows use the following commands: # cd $CA_WCC_INSTALL_LOCATION/bin # StopWCCServices.bat # StartWCCServices.bat

(4)

Generate a Secret Key and Request a Certificate

The second method of changing the certificate is to generate a secret key and request a certificate. The process is as follows: 1. Generate a key and request 2. Send the request to your C.A. 3. Add the certificate chain in the keystore 4. Insert your certificate into the keystore 5. Restart CA WCC services Note: File extensions used for certificates have several standards. The following extensions are used in this document: • csr—Certificate request • der—Certificate, encoded in Der (binary) • cer—Certificate, encoded in PEM (text)

Generate a Key and Request

To generate the secret key: 1. Perform steps 1 and 2 in the Generate a Self‐signed Certificate section. Notes: • Do not restart CA WCC services. • A self signed certificate will be generated. That certificate will be overwritten in a later procedure. 2. Issue a request file (certreq.csr) with the following command:

# $CA_WCC_INSTALL_LOCATION/jre/bin/keytool -certreq -alias tomcat \

-keystore $CA_WCC_INSTALL_LOCATION/config/.keystore -storepass changeit \ -file certreq.csr

Send the Request to your C.A.

Using the request file (certreq.csr), obtain a certificate in PEM format from your C.A. How this certificate is obtained differs on every C.A. Typically, you will send the request file (certreq.csr); the C.A. will also require some proof of your identity.

(5)

Retrieve the Certificate Chain

While you are waiting to obtain the certificate, you must insert the public certificates of the root C.A. into the keystore, plus possibly several Sub C.A.s. This is because typically, a C.A. does not issue certificates directly. Instead they delegate to a Sub C.A., which can in turn delegate to another Sub C.A., and so on. The list of the Root Certificate and Sub‐C.A.s is referred to as the certificate chain. The public certificate of the C.A. and Sub‐C.A.s are always available on the website of the C.A. (Certificate Authority). In case a PEM version is not available, the following section describes how to convert from DER to PEM, and also how to clean a PEM certificate to make sure it will be understood by the keytool program.

Converting and Cleaning the Certificate

Certificates are usually available in DER or PEM format. If the certificate is in DER format, it must be converted to PEM format. If the certificate is in PEM format, it must be cleaned.

Convert the Certificate from DER to PEM

When you obtain a certificate in DER format you must convert it to the PEM format. The certificate is also cleaned during the conversion. To convert a DER certificate to PEM format and clean it, use the following command:

# openssl x509 –inform DER –in certificate.der –out certificate.cer

Clean a PEM Certificate

When you obtain a certificate in PEM format, it can contain optional information which should be removed because the keytool program will not understand it. Cleaning the PEM certificate removes the optional information. Unless you obtained your certificates in PEM format by converting them from DER using the command in the previous section, it is recommended that you run the following command to remove this optional information and obtain a clean PEM:

# openssl x509 –in certificate-with-extra-info.cer –out certificate.cer

This command is safe to run when the original certificate is already clean.

Insert the Certificate Chain into the Keystore

Once you have downloaded the certificate of the root C.A. and converted it or cleaned it, you must run the following command:

# $CA_WCC_INSTALL_LOCATION/jre/bin/keytool -importcert -alias RootCA \ -file RootCA.cer \

(6)

If your certificate is issued by a sub‐CA, you must also download the certificate of the Sub‐C.A., convert it or clean it, and then run the following command:

# $CA_WCC_INSTALL_LOCATION/jre/bin/keytool -importcert -alias SubCA \ -file SubCA.cer \

Obtain the Certificate and Insert the Certificate into the Keystore

When you receive your certificate, do the following:

1. Convert the certificate to a clean PEM as described in the Converting and Cleaning the Certificate section.

2. Insert the certificate into the keystore with the following command:

# $CA_WCC_INSTALL_LOCATION/jre/bin/keytool -importcert -trustcacerts \ -file certificate.cer –alias tomcat \

And keytool should reply with: ‘Certificate reply was installed in keystore’

Restart CA Services

Finally, restart the CA WCC services. On Unix use the following commands: # cd $CA_WCC_INSTALL_LOCATION/bin # ./StopWCCServices.sh # ./StartWCCServices.sh On Windows use the following commands: # cd $CA_WCC_INSTALL_LOCATION/bin # StopWCCServices.bat # StartWCCServices.bat

(7)

Import an Existing Key and Certificate

The third method of changing the certificate is to import an existing key and certificate. You can either reuse an existing .keystore file or import a private key and certificate from a Pkcs12 file. You must then restart the CA Services.

Reusing an Existing .keystore File

If you want to move your .keystore file from a 11.1.sp2 wcc installation, you can simply copy the ConfigServer/conf/.keystore file from your 11.1sp2 installation to the following location in r11.3: $CA_WCC_INSTALL_LOCATION/config/.keystore

Importing from a Pkcs12

If you have a private key and certificate packaged as a Pkcs12, you can install it in the keystore with the following commands: # $CA_WCC_INSTALL_LOCATION/jre/bin/keytool -importkeystore \

-srckeystore myp12.p12 -srcstoretype PKCS12 -srcstorepass my-password \ -deststorepass changeit -destkeypass changeit \

-destkeystore $CA_WCC_INSTALL_LOCATION/config/.keystore \ -alias 1 –destalias tomcat

Note: The certificate chain found in the Pkcs12 will be imported into the keystore (although it is not visible with the keytool program). In case the C.A.’s certificate was not provided inside the Pkcs12, you can import it as described in the Insert the Certificate Chain into the Keystore section.

Restart CA Services

The final step is to restart the CA WCC services. On Unix use the following commands: # cd $CA_WCC_INSTALL_LOCATION/bin # ./StopWCCServices.sh # ./StartWCCServices.sh On Windows use the following commands: # cd $CA_WCC_INSTALL_LOCATION/bin # StopWCCServices.bat # StartWCCServices.bat Note: Although it is outside of the scope of this document , it should be mentioned that it is usually possible to reassemble a Pkcs12 based on keys and certificates found in .keystore (as used by Tomcat) or separate PEM files (as used by Apache) with the openssl p12 command.

(8)

Troubleshooting

This section contains solutions to problems you may encounter. 1. Problem: I get the following SecurityAlert in my browser: The name on the security certificate is invalid or does not match the name of the site. Solution: You can get this error when trying to access CA WCC using localhost. For example, https://localhost:8443/wcc. You can also receive this error if the URL you used to connect to CA WCC does not match the CN attribute of the certificate Issued To field exactly. For example, https://wcc01:8443/wcc will cause a SecurityAlert if the CN attribute of the certificate Issued To field is wcc01.ca.com. The solution is to use the name of the server as it is specified in the CN attribute of the certificate Issued To field. For example, https://wcc01.ca.com:8443/wcc. 2. Problem: I get a SecurityAlert in my browser even though I am using a genuine Certificate Authority generated certificate. The CN attribute of the certificate Issued To field matches the hostname/URL that I used to access CA WCC. Solution: You may need to check with the Certificate Authority about whether or not a Chain Certificate is needed in the keystore to establish the full authenticity of the certificate.

(9)

Changing WCC’s server name

A computer can have several DNS name, and the certificate that you obtained might be for a different DNS name than the name entered during WCC installation.

When connecting with https, the name used in the network address (URL) must match the name in the certificate, otherwise a “Hostname mismatch” certificate error will be displayed. Hence it might be necessary to change WCC’s server name so that it matches the name in the

certificate, and this section describes how.

It is assumed that the file $CA_WCC_INSTALL_LOCATION/config/.keystore has already been updated following one of the methods above.

Notes

• Since this procedure involve modifying several configuration files, please make a complete backup of your WCC installation directory before beginning.

• WCC supports only one name, i.e. after the server’s name is changed, accessing WCC with the previous name might not work correctly.

Identify the name in the certificate

This step is optional.

Should you want to double check the name in the certificate, it is possible to do so with the keytool command:

# $CA_WCC_INSTALL_LOCATION/jre/bin/keytool \

-list -keystore $CA_WCC_INSTALL_LOCATION/config/.keystore \ -storepass changeit -alias tomcat -v

The command will output all the certificates used by tomcat. Typically there will be one for the WCC server, and one for the C.A.’s and/or sub‐C.A.’s.

Each certificate printout will contain a line starting with ‘Owner: CN=’.

In the server’s certificate, the name of the server is contained between Owner:CN= and the first following comma. E.g. if your server’s name is www.acme.com, , you should see something similar to:

Alias name: tomcat

Creation date: May 11, 2011 Entry type: PrivateKeyEntry Certificate chain length: 2 Certificate[1]:

Owner: CN=wcc.acme.com, O=Internet Widgits Pty Ltd, ST=Some-State, C=AU Issuer: CN=Dummy, O=Internet Widgits Pty Ltd, ST=Some-State, C=AU

(10)

Update the configuration files to use the server’s name as in the certificate

In the following files (relative to $CA_WCC_INSTALL_LOCATION), replace the name used during the installation by the name used in the certificate. Any method can be used, including a search and replace with a text editor. ConfigServer/config/application/config/resources/internal-componentURLs.properties ConfigServer/config/application/config/resources/internal-install.properties ConfigServer/config/application/config/resources/internal-misc.properties ConfigServer/config/application/mainui/themes/Theme1/tab1.properties ConfigServer/config/application/mainui/themes/Theme1/tab10.properties ConfigServer/config/application/mainui/themes/Theme1/tab11.properties ConfigServer/config/application/mainui/themes/Theme1/tab12.properties ConfigServer/config/application/mainui/themes/Theme1/tab2.properties ConfigServer/config/application/mainui/themes/Theme1/tab3.properties ConfigServer/config/application/mainui/themes/Theme1/tab4.properties ConfigServer/config/application/mainui/themes/Theme1/tab5.properties ConfigServer/config/application/mainui/themes/Theme1/tab6.properties ConfigServer/config/application/mainui/themes/Theme1/tab7.properties ConfigServer/config/application/mainui/themes/Theme1/tab8.properties ConfigServer/config/application/mainui/themes/Theme1/tab9.properties product.xml

_uninst/Uninstall_CA Workload Control Center/installvariables.properties _uninst/Uninstall_WCCApplicationServerConfig/installvariables.properties

Restart CA Services

The final step is to restart the CA WCC services. On Unix use the following commands: # cd $CA_WCC_INSTALL_LOCATION/bin # ./StopWCCServices.sh # ./StartWCCServices.sh On Windows use the following commands: # cd $CA_WCC_INSTALL_LOCATION/bin # StopWCCServices.bat # StartWCCServices.bat