Configuring Secure Sockets Layer (SSL)

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:

• IHS guide to setting up SSL
• Knowledge Center Security topic
• IKeyman "How to" document
• IHS technote for ClearCase

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:

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.

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

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

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:

• WebSphere Application Server forum on installing your own certificates: https://www.ibm.com/developerworks/community/forums/html/topic?id=b3b2ef84-ce0c-4e9d-92ae-45e24b48258a&ps=25
• IHS certificate management: https://www.ibm.com/support/knowledgecenter/SS7K4U_8.5.5/com.ibm.websphere.ihs.doc/ihs/cihs_certmgmt.html
• IHS key management: https://www-01.ibm.com/support/knowledgecenter/SS7K4U_8.5.5/com.ibm.websphere.ihs.doc/ihs/welc_ikeymangui.html

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.