1. Generate the Keystore, create an Alias and Key Pair
- Stop the Connect for IBM Rational service if it is running.
- Open a command prompt and navigate to the following directory: \iRiseConnect for IBMRational\jvm64\jre\bin
- Type the following command, entering whatever name you like for the alias (make note of the name you use for the alias as you will use this later). Please note that you will need to use lower case to create the alias, and also later on when you add it to the server.xml file.:
keytool -genkeypair -alias <alias> -keyalg RSA -sigalg SHA256withRSA -keypass <key password> -keystore <\iRiseConnectforIBMRational\tomcat\conf\keystore.jks> -storepass <keystore password> -validity <number of days key is valid> -keysize 2048
- Enter the following information when prompted:
first and last name - the Keytool program is looking for the common name here. The common name is the fully-qualified domain name (FQDN), Host name or URL - to which you plan to apply your certificate. Do not enter your personal name in this field. NOTE: If you are requesting a Wildcard certificate, please add an asterisk on the left side of the Common Name (e.g., "*.coolexample.com" or "*www.coolexample.com"). This will secure all subdomains of the Common Name.
organizational unit - Use this field to differentiate between divisions within your organization. For example, "Engineering" or "Human Resources." If applicable, you may enter the DBA (doing business as) name in this field.
organization - The name under which your business is legally registered. The listed organization must be the legal registrant of the domain name in the certificate request. If you are enrolling as an individual, please enter the certificate requestor's name in the Organization field, and the DBA (doing business as) name in the Organizational Unit field
city/locality - Name of the city in which your organization is registered/located. Please spell out the name of the city. Do not abbreviate.
state/province - Name of state or province where your organization is located. Please enter the full name. Do not abbreviate.
country code - The two-letter International Organization for Standardization- (ISO-) format country code for the country in which your organization is legally registered.
Keytool will present you with a Distinguished Name (DN), which includes the FQDN, hostname or URL you entered. Please confirm the DN information is correct.
2. Modify the server.xml file
- Make a copy of the \iRiseConnectforIBMRational\tomcat\conf\server.xml file
- Edit the server.xml file with a text editor.
- Find the connector by searching for "Service name=Catalina". The connector will only contain the port. You will need to modify the port and add the rest of the information listed below:
keystoreFile="<path to your keystore file>"
keystorePass="<password to your keystore>"
keyPass="<password to private key>"
keyAlias="<alias to your key created above>"
3. Test your settings and your self-signed certificate
- Start the iRise Connect for IBM Rational service, then open a browser on the DC server and try to login to https://servername. If you used a port other than 443 type https://servername:<port> replacing <port> with the port number you used
- Attempt to login to the iRise Connect for IBM Rational and navigate around. You will get a security warning in your browser indicating that the certificate for the server is not signed from a trusted authority. This is expected, as the certificate is self-signed at this point. If you do not intend on having a certificate authority (CA) sign your certificate, you can export your certificate from the keystore and import it into your system's trusted store. If you require a trusted CA to sign your certificate, continue to step 4 to create a certificate signing request (CSR). Otherwise run this command to export your certificate:
keytool -export -keystore <path to keystore file> -alias <alias> -file <certificate name>.cer
Run these commands to import self-signed certificate into Windows client:
certutil -addstore "TrustedPublisher" <certificate name>.cer
certutil -addstore root <certificate name>.cer
Import self-signed certificate into Mac client:
sudo /usr/bin/security add-trusted-cert -d -r trustRoot -k "<certificate name>.cer"
4. Generate a Certificate Signing Request (CSR) and Obtain a Certificate
Open a command prompt and navigate to the following directory: \iRiseConnectforIBMRational\jvm64\jre\bin.
Generate the CSR using the following command:
keytool -certreq -alias <alias> -sigalg SHA256withRSA -file <filename.csr> -keypass <key password> -storetype jks -keystore <path to keystore.jks> -storepass <keystore password>
You should now have a CSR in the directory specified in the above command. Open the file with a text editor and cut and paste the contents into your certificate authority’s enrollment form and follow the instructions to generate your certificate.
5. Install and Test your Certificate
If given a choice, choose a P7B type certificate, as it contains the full chain, including the root and intermediate certificates. Open a command prompt and navigate to the following directory: \iRise\DefCenter\jvm64\jre\bin
Import the signed certificate into the keystore with the following command:
keytool -import -file <signed certificate> -alias <alias> -trustcacerts -keystore <path to keystore> -storepass <keystore password>
If you used a certificate from a trusted root authority (Verisign, Thawte, etc.) you don't need to do anything more. Start the iRise Connect for IBM Rational service and go to https://<servername>/iriseconnectrc/login.htm (or https://<servername>:<port>/iriseconnectrc/login.htm if not using port 443) in a browser to test the configuration.
Non-trusted Certificate Authority - additional steps
If you used a certificate from a non-trusted or internal certificate authority, there are some additional steps you need to take. You need to import that certificate authority's root & intermediate (if using) certificate(s) into the \iRiseConnectforIBMRational\jvm64\jre\lib\security\cacerts file. Additionally, if there are intermediate certificate signing servers between the root authority and your certificate, you need to import the root certificates for those intermediate signing servers to the \iRiseConnectforIBMRational\Tomcat\conf\keystore.jks file. You can do this using the keytool program as well. Here is a sample command for importing a root certificate (rootcert.cer) into the cacerts file:
keytool -import -trustcacerts -file rootcert.cer -alias <mycompanyroot> -keystore \iRiseConnectforIBMRational\jvm64\jre\lib\security\cacerts
and here is a sample command for importing an intermediate signing authority certificate (intermediate.cer) into the keystore.jks file
keytool -import -trustcacerts -alias <mycompanyintermediate> -file intermediate.cer -keystore \iRiseConnectforIBMRational\Tomcat\conf\keystore.jks
You can use the free Keystore Explorer tool (available for Windows and Mac) to create and read keystore files and examine and import certificates. Further details can be found on their website: http://keystore-explorer.sourceforge.net.