IBM Support

Configuring Secure Sockets Layer (SSL)

Question & Answer


Question

How do I configure SSL for ClearCase?

Answer

Following are instructions for configuring ClearCase Remote Client (CCRC) Wide Area Network (WAN) Server to use Secure Sockets Layer (SSL). It also explains how to add trusted certificate authorities for use with change management integrations using ClearCase's Change Management Integration (CMI), the UCM-ClearQuest web integration (CALAMARI (OSLC)) and the Base ClearCase-ClearQuest V2 integration (perl triggers).

1 CCRC WAN server SSL installation and validation

The steps below were used to configure IBM WebSphere Application Server and IBM HTTP Server, version 8.5.5. For additional reference materials, refer to these documents:

1.1 Install WAS and IHS
  • Download the installation repositories for WebSphere Application Server and IBM HTTP Server, versions 8.5.5.
  • Launch IBM Installation Manager.
  • Add the WAS and IHS repositories to IM.
  • Install IHS and WAS on your CCRC WAN server host.

1.2 Install ClearCase
  • Download the ClearCase installation repository.
  • Launch IBM Installation Manager.
  • Add the ClearCase repository to IM.
  • Install ClearCase. Select the "CCRC WAN server" package, and if applicable, the "Automatic View WAN server" package.

1.3 Verify the connection

After you have installed IHS, WAS, and ClearCase, you will have defined a WAS profile for ClearCase and a connection from IHS to WAS. Verify the IHS/WAS connection is working by accessing:

http://hostname/ccrc/admin/version

You should see a listing of the ClearCase software version like this:

ClearCase version 8.0.1.09 (Wed Sep 16 13:47:01 EDT 2015) (8.0.1.09.00_2015C.FCS)
@(#) MVFS version 8.0.1.09 (Wed Sep 16 23:12:38 2015)
cleartool                         8.0.1.09 (Mon Sep 9 23:17:59 2015)
db_server                         8.0.1.09 (Wed Sep 14 00:33:06 2015)

These messages confirm that the server connection using unencrypted HTTP is operational.

2 Configuring SSL

The information that follows is an abbreviated explanation of the material covered in the IHS setup guide referenced above.

2.1 Enable SSL processing in IBM HTTP Server

Edit the IHS configuration file (under the installation directory, in conf/httpd.conf). Find the SSL section and uncomment the lines. If any pathnames have spaces, use double-quotes around the pathnames; for example,

KeyFile "C:/Program Files (x86)/IBM/HTTPServer/ihsserverkey.kdb"

2.2 Create a server key for IHS

Create a server key and key file for IHS. The IKeyman "how to" document linked above has instructions. Create the key file in the location specified in the httpd.conf file. Stash the password when you create the file.

Note: If you are running on Windows with User Account Control (UAC) enabled, you must start the ikeyman GUI with administrator privileges, otherwise the key file may be created in a virtual directory instead of in the location listed in httpd.conf. When selecting the "Start Key Management Utility" menu item, use a right-button click and select "Run as Administrator"

If you have a certificate for your server, install it as the default personal certificate using the "Receive" operation. Otherwise, use the "Create" menu to make a new certificate request or self-signed certificate. If you are using a self-signed certificate, proceed to the next step. If you are requesting a CA-signed certificate, return to the GUI when you have received the certificate, and install it as the default personal certificate. Also install all the CA signing certificates in the chain of certificates from the CA.

Restart the IHS server (Windows services GUI, or UNIX/Linux startup script) and use a browser to test your connection to IHS: connect to https://server/

If you get a certificate warning for a CA-signed certificate, examine the details of the certificate shown by the browser—you may need to install a private certificate authority root key into your browser or you may need to install intermediate signing certificates in the IHS keystore.

At this point, SSL is configured between the client and IHS. Next, configure SSL between IHS and WAS.

2.3 Configure the IHS-to-WAS connection

IHS 8.5 and WAS 8.5 use an SSL connection between IHS and WAS whenever the client uses an SSL connection to IHS. You must configure IHS to trust the WAS server’s SSL identity before CCRC will communicate successfully through https to IHS.

Every time a new WAS profile is generated, you must import two certificates from the WAS profile’s keyring, installing them into the IHS keyring

Note: A new profile is generated whenever you deinstall ClearCase and reinstall it; and whenever you upgrade ClearCase to a new release.

Find the WAS profile keyring: Navigate to the CCRC WAS profile directory (typically RationalSDLC/common/ccrcprofile). Inside this directory you need the plugin-key.kdb file, inside one of the cell’s configurations. The node name should be based on the hostname. Sample path: config/cells/dfltCell/nodes/qlnx064-node/servers/webserver1/plugin-key.kdb

Next, use the IKeyman GUI to open the key file; the password is WebAS. (On Windows, run IKeyman as administrator.) Select the Personal Certificates section, select the one certificate, and use "Extract Certificate" to save it as ASCII. Select the "Signer Certificates" section, select the one certificate, and extract it to a different file name. You may be able to accomplish this by opening config/cells/dfltCell/nodes/dfltNode/key.p12 and config/cells/dfltCell/nodes/dfltNode/root-key.p12 one at a time and exporting the key(s) into the IHS keyring

Find the IHS keyring: In the httpd.conf file, find the line with WebSpherePluginConfig. That line lists the name of the file with the plugin configuration for the CCRC profile. Open the file in an editor and review the settings. Look for the section with the port number of the CCRC profile (usually 16443), and note the pathname to the keyring file. (On Windows, edit httpd.conf as administrator.)

Note: If you install the 32-bit IHS and WAS on 64-bit Windows servers, the pathnames for the key and stash files may use Program Files instead of Program Files (x86). Look in the file system to ensure the listed file names exist, and change the references to use Program Files (x86) if necessary. You must repeat this step every time you reinstall or update ClearCase.

Install certificates in IHS keyring: Use the IKeyman GUI to open the IHS keyring you identified above (the password is WebAS). Select the "Signer Certificates" section. Use "Add…" to import the two certificates that you extracted. Use any name for the labels.

2.4 Testing the IHS-to-WAS connection

Restart IHS, then connect with a browser to https://server/ccrc/admin/version. If you see the same ClearCase version details that you saw previously, you have successfully configured SSL. If you see an internal server error, check the IHS log files and the plugin log files (the pathnames are listed in the plugin configuration XML file).

3 Installing CA or server certificates on the CCRC client

The ClearCase Remote Client (CCRC), which encompasses ClearTeam Explorer (GUI), rcleartool (CLI), and CMAPI Java classes, uses the Java runtime (JRE) implementation of SSL. The JRE has a built-in default list of certificate authorities. CCRC uses an additional keystore to hold certificates that you accept as exceptions.

  • If you have your own private certificate authority (CA), such as for an intranet deployment, you must import the CA certificates into your client environment.
  • If you use self-signed certificates (not recommended) on your servers, you need to import them exactly as you would import a private CA root certificate.

4 Installing CA or server certificates for Change Management Interface (CMI) and the UCM-ClearQuest web integration (CALAMARI)

If you use CALAMARI or the CMI integration with any supported change management solution (such as ClearQuest, Rational Team Concert, Jira, etc.), you may need to install private certificate authority certificates or self-signed server certificates to enable SSL connections. ClearCase is configured with trusted certificate authorities as provided by the IBM Java runtime environment.

4.1 Desktop clients on Windows

The CMI and CALAMARI integrations use the default per-user keystore provided by Windows. Users who do not have the private CA or self-signed certificates installed in their keystores can use the certificate manager GUI to install it (see Microsoft’s technet document Import a Certificate). The command certmgr.msc starts the certificate manager GUI.

5 Installing additional CA or server certificates for the Base ClearCase/ClearQuest integration

If you need additional CAs for your environment, you can configure them in the integration’s config.pl script. This file must be available on all systems that execute the integration code: developer/end-user systems with the local client (dynamic/snapshot views) and CCRC WAN servers. See LWP::UserAgent→new() in UserAgent.pm to explore the effect of all these environment variables.

  • PERL_LWP_SSL_CA_FILE: If you have your certificate authority in a single PEM file (multiple certificates can be put in a single file), set the environment variable to point to this file:
    $ENV{PERL_LWP_SSL_CA_FILE} = "/path/to/my/CA/file.pem";
  • PERL_LWP_SSL_CA_PATH: If you have a set of certificates, each in its own PEM file, hashed with the c_rehash command, set the environment variable to point to this directory:
    $ENV{PERL_LWP_SSL_CA_PATH} = "/path/to/my/CA/directory";
  • PERL_LWP_SSL_VERIFY_HOSTNAME: To disable hostname checking (not recommended), set this environment variable to any value:
    $ENV{PERL_LWP_SSL_VERIFY_HOSTNAME} = "off";

ClearCase can be configured to use Secure Sockets Layer (SSL) to protect certain data transferred over the network. For complete protection, this requires that the SSL client verifies the SSL server's identity, as sent with an SSL certificate. The SSL client verifies that the server certificate is signed by a chain of certificates leading to a root certificate that the client trusts, and that the server certificate name matches the hostname used for the connection.

ClearCase includes a set of trusted certificate authorities (CAs) in its default installation. The CAs are provided by the IBM Java Runtime Environment that is installed with ClearCase, except for the Base ClearCase/ClearQuest v2 integration, which uses a list of CAs from the Mozilla::CA Perl package.

Important: To configure your SSL servers, you will need to acquire a trusted certificate for each server and the name in the certificate must match the server hostname.

Certificate files

Trusted certificate authorities can be found in the following files:

  • ClearCase remote client (CCRC RCP):
    • Default: the CA's are included in the IBM Java Runtime Environment installed with ClearCase.
    • User customized: the CA's are included in the Java Runtime Environment configured by the user on CCRC startup or in the ccrc.ini file.
  • CCRC plugin: the CA's are included in the Java Runtime Environment configured by the user for the Eclipse IDE.
  • Base CC/CQ v2 (Perl) integration: this integration uses a list of CAs from the Mozilla::CA Perl package.
  • The Change Management Integration (CMI): this integration uses CAs from the Java Runtime Environment that is installed with ClearCase, reformatted into a compatible keystore file format.

Certificates are commonly stored in files in either a binary form (DER, sometimes named .der or .crt) or text form (PEM, with a first line like -----BEGIN CERTIFICATE-----, sometimes named .asc or .pem). Depending on the form provided by your certificate authority, you may need to convert it from DER to PEM format for some of the uses listed below; for example:

openssl x509 -inform DER -in carootcert.der -outform PEM -out carootcert.pem

For more information on openssl, refer to https://www.openssl.org/docs/manmaster/apps/openssl.html

Using a certificate signed by an authority

If the authority is already listed in the standard trusted CA list, you need only to install the certificate into the SSL server. If you use a private CA (such as a CA operated by your IT department), you also need each client to add the CA root key to the relevant trusted CA list. Once you do this, the private CA will be trusted to identify any server as long as the server certificate's hostname matches the hostname used for a connection. Several parts of ClearCase are SSL clients and need to trust the server's CA.

Requirements for ClearTeam Explorer, CMAPI, and rcleartool

The client environment needs to trust the CCRC WAN server's certificate. Each user should add the CCRC WAN Server's CA root certificate to their .keystore_clearcase file (in the user's home directory on the client machine). Alternatively, each user must verify the certificate on the first connection and save it permanently. If the user accepts a certificate exception, he should use information from the administrator to confirm that the certificate is legitimate.

To accept the CA root certificate, the user should get a copy from the server administrator via a trusted source. The administrator should supply the CA root certificate in a file in base64/PEM format or DER format. Then each user should import the certificate and mark it as trusted using the keytool command (found in the IBM JRE shipped with ClearCase):

  • Windows: RationalSDLC\common\JAVA\jre\bin\keytool.exe (or JAVA5.0 for older releases)
  • UNIX/Linux:

    
    navigate to user's home directory 
     /opt/rational/common/java/jre/bin/keytool -storetype JKS -keystore .keystore_clearcase -storepass rational -importcert -alias SOME-NAME-FOR-ROOT-CA -file path/to/caroot.file
    
    

    When prompted, answer "yes" to the question of trusting the certificate.

Requirements for the Base ClearCase / ClearQuest V2 integration (perl triggers)

The scripts need to trust the SSL certificate of the CQWeb server. The integration administrator should create a file with the PEM-encoded CA root certificate, and name that in the config.pl file. The administrator should also explicitly enable hostname checking--it is normally enabled but becomes disabled when setting an alternate CA file. Add a statement like the following to the ConfigureTrigger method in config.pl:

$ENV{HTTPS_CA_FILE} = "/path/to/file.pem";$ENV{PERL_LWP_SSL_VERIFY_HOSTNAME} = 1;

Requirements for Change Management Integration (CMI) and the UCM-ClearQuest Web integration on UNIX/Linux (client or WAN server)

The clients need to trust the change management server's certificate. The ClearCase administrator should append the PEM-encoded CA root certificate to /var/adm/rational/clearcase/config/cacert.pem.

Requirements for Change Management Integration (CMI) and the UCM-ClearQuest Web integration on Windows (client)

The clients need to trust the change management server's certificate. The user should add the PEM or DER encoded CA root certificate to the Windows account's trusted key stores (not to .keystore_clearcase). Use the certmgr.msc tool or refer to Microsoft’s technet document https://technet.microsoft.com/en-us/library/cc754489.aspx.

Requirements for Change Management Integration (CMI) and the UCM-ClearQuest Web integration on Windows CCRC WAN server

The WAN server must trust the CA in its private trusted key store. The WAN server administrator should add the PEM or DER encoded CA root certificate to the store (the file ccrc_ucmcq_key.kdb is included in the CCRC WAN Server installation). Use the gsk8capicmd command-line tool to modify this keystore. For example, if ClearCase is installed into C:\Program Files (x86)\IBM\RationalSDLC, use the command:

gsk8capicmd -cert -add -stashed -db "C:\Program Files (x86)\IBM\RationalSDLC\ClearCase\config\ccrc\ccrc_ucmcq_key.kdb" -file trusted-certificate-file.pem

Using a self-signed certificate

If you need to use a self-signed certificate, its hostname must match your server's hostname. You can install that specific certificate exactly as you would install a private CA root certificate (refer to the previous section). It will be trusted only to identify those servers whose hostnames match the hostname(s) listed in the certificate.

Requesting and installing a certificate signed by a CA

To create a new server key and certificate, refer to the help topic, Overview of Security Considerations. That topic has a link to the IBM HTTP Server instructions for SSL setup. That document has a link to "IKEYMAN, how do I ...?" with instructions for generating a key and a certificate signing request, and installing the resulting certificate returned from your CA.

If your users use an URL that connects directly to the CCRC WAN server WAS profile (this is supported but not recommended: we recommend using the IHS plugin connection for SSL and non-SSL clients): use the WAS admin console or ikeyman tool for requesting/receiving a signed certificate and installing that as the profile's certificate.

If you have an existing certificate and private key, you can import it into the IHS keystore or WAS keystore using the ikeyman tool. Select the "Personal Certificates" section in the middle, then use the "Export/Import..." action on the right. For more information:

Upgrading to a new release

When upgrading to this release, users must delete any existing .keystore_clearcase files and recreate them, adding only the additional trusted CA root certificates and trusted self-signed certificates.

  • On Windows: The key database ccrc_ucmcq_key.kdb and related files are copied from a template upon the first installation of ClearCase on a host. It is preserved during upgrades or deinstall/reinstall. If you wish to upgrade to the latest version of this file shipped by ClearCase, make a new copy from the original: ccase-dir\clearCase\config\ccrc_ucmcq_key.template.kdb and related files (.sth and .rdb).
  • On UNIX/Linux: The cacert.pem file is copied from a template upon the first installation of ClearCase on a host. It is preserved during upgrades or deinstall/reinstall. If you wish to upgrade to the latest version of this file shipped by ClearCase, make a new copy from the original: /opt/rational/clearcase/config/cacert.pem.template.

Use the following table to diagnose and fix problems that affect your specific client/server/certificate configuration.

Client Server SSL Certificate installed on server Problem Solution
ClearTeam Explorer (CTE), rcleartool, or CMAPI CCRC WAN server, installed by ClearCase to create a new WAS profile and configured with IHS to redirect to CCRC WAN server (Server URL: https://server_name/ccrc) IHS server has a key/certificate installed Users are unable to log in. A test connection to the server with a web browser to https://server_name/ccrc/admin/version displays an internal error.

Possible causes:

* IHS may not trust the certificate presented by the WAS profile for CCRC.

* On Windows 64-bit servers, incorrect generated pathnames.
To diagnose and resolve these problems, refer to tech note http://www.ibm.com/support/docview.wss?uid=swg21978296.
CCRC WAN server via IHS or direct to WAS Self-signed certificate installed CTE displays a certificate error dialog box There are two options for resolving the problem:

* Verify the certificate details with the WAN server administrator, then accept the certificate for the specific hostname/port (optionally storing it permanently for future sessions).

* Have the administrator install a new certificate into the IHS or WAN server. The certificate would be signed by a trusted certificate authority (CA).

NOTE: There could be a charge for this service.
Certificate is signed by a certificate authority CTE displays the message, "The certificate was issued by an unknown authority." The certificate authority is not in the default list:

* Recommended option: If you trust this certificate authority (perhaps it is a company-internal CA), get the root CA certificate and install it into each user's .keystore_clearcase (see below).

* Another option: users verify certificates against details provided by the CCRC administrator, then they accept them.
CCRC WAN server Any CTE displays the message, "The certificate's name is different than the server name" Either correct the URL to use the hostname listed in the certificate or issue a new certificate with the correct hostname.
Base ClearCase / ClearQuest V2 integration (using perl triggers) ClearQuest Web Certificate signed by a certificate authority Perl triggers fail to connect with the error, "CQWebJava XML Parsing error." If you set CQCC_DEBUG to 2 in the config.pl file, the extended debug information shows "certificate verify failed". The problem could be that the issuing certificate authority is not trusted. Create a file with a PEM-encoded copy of the trusted certificate authority's root certificate. In the trigger script's config.pl file, inside the ConfigureTrigger subroutine, provide the pathname to this file:

$ENV{HTTPS_CA_FILE} = "/path-to-file.pem";

and set the variable to check the certificate's hostname:

$ENV{PERL_LWP_SSL_VERIFY_HOSTNAME} = 1;
Self-signed certificate
Any Perl triggers fail to connect with error "CQWebJava XML Parsing error." If you set CQCC_DEBUG to 2 in the config.pl file, the extended debug information shows "certificate verify failed". The problem could be that the certificate hostname does not match the URL. Either correct the CQCC_SERVER value to use the hostname listed in the certificate or issue a new certificate with the correct hostname.
Change Management Integration (CMI) or Web Client Integration (UNIX/Linux) Any supported change management server Self-signed certificate The error message includes the text, "self signed certificate in certificate chain". The problem could be that the self-signed certificate is not trusted. Either issue the certificate from a trusted CA, or trust the self-signed certificate, as follows:

1. Create a file with a PEM-encoded copy of the trusted self-signed server certificate.

2. Append this file to

/var/adm/rational/clearcase/config/cacert.pem.

This certificate will be trusted to identify the specific server hostname.
Certificate signed by a certificate authority The error message includes the text, "self signed certificate in certificate chain". The problem could be that the certificate authority is not trusted. Either issue the certificate from a trusted CA, or add the certificate authority to the list of trusted CAs, as follows:

1. Create a file with a PEM-encoded copy of the authority's root certificate.

2. Append this file to

/var/adm/rational/clearcase/config/cacert.pem.

This certificate authority will be trusted to sign any server certificates when using these clients.
Any The error message includes the text, "certificate subject name 'xxx' does not match target host name 'yyy'" or "no alternative certificate subject name matches target host name 'yyy'" Either correct the URL to use the hostname listed in the certificate or issue a new certificate with the correct hostname.
Change Management Integration (CMI) or Web Client Integration (Windows) Any supported change management server Self-signed certificate The error message is "no trusted CA chain." Either issue the certificate from a trusted CA, or trust the self-signed certificate, as follows:

1. Extract the server's certificate into a file (use a web browser, view the certificate, save to a file).

2. Import the certificate into the user's certificate store. (GUI tool: certmgr.msc)
Certificate signed by a certificate authority Either issue the certificate from a trusted CA, or add the certificate authority to the list of trusted CAs. Users must add the certificate authority to the list of trusted certificates:

1. Obtain the certificate authority root certificate from a trusted source. Add it to a file.

2. Import the certificate into the users' certificate stores. (GUI tool: certmgr.msc)
Any The error message could be either, "GSKIT_connect_step3 (hostname validation) failed" or "certificate subject name 'xxx' does not match target host name 'yyy'
Change Management Integration (CMI) or or Web Client Integration running on Windows CCRC WAN Server on behalf of Web or Automatic views Various problems or errors The CCRC WAN Server administrator must ensure the change management server's certificate chain is trusted.

(See the first tab of this document: "About SSL certificates.")
Change Management Integration (CMI) or or Web Client Integration running on UNIX/Linux CCRC WAN Server on behalf of Web or Automatic views Follow the suggestions for CMI on a UNIX desktop client.

[{"Product":{"code":"SSSH27","label":"Rational ClearCase"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":"--","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"}],"Version":"9.0.1.2;9.0.1.1;9.0.1;9.0.0.1;9.0;8.0.1.11;8.0.1.10;8.0.0.18","Edition":"","Line of Business":{"code":"LOB15","label":"Integration"}}]

Document Information

Modified date:
11 September 2019

UID

swg21976656