Secure Sockets Layer (SSL) certificate

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

Note: To configure your SSL servers, you 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):
    • Default: the CA's are included in the IBM Java Runtime Environment is 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: uses a list of CAs from the Mozilla::CA Perl package.
  • The Change Management Integration (CMI): this integration uses CA's 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 might 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/man1/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 on 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 trusts you 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. For information about the certificate needs, see Certificate requirements for integrations.

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 trusts 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 Configuring Secure Sockets Layer (SSL). For instructions on generating a key and a certificate signing request and installing the resulting certificate returned from your CA, see the IKEYMAN document.

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 or 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 uninstall/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 uninstall/reinstall. If you wish to upgrade to the latest version of this file shipped by ClearCase®, make a new copy from the original: /opt/devops/ClearCase/config/cacert.pem.template.