Modifying IBM Rational Change 5.2 (Jetty / WASCE / WAS) to use SSL/HTTPS

Answer

Overview

This document is intended for use by Rational Change administrators who want to modify Rational Change to have SSL/HTTPS support with a 128-bit encryption key. Below are the steps to allow Rational Change to use SSL/HTTPS for secure communication.

Keystore generation

1. Change directory to $JAVA_HOME\jre\bin.


JAVA_HOME for Jetty: $CCM_HOME\jre\bin
JAVA_HOME for WASCE: Find it from $WASCE_HOME\bin\setenv.bat


2. Generate the keystore file

A new key and a self-signed certificate can be generated and loaded using the standard JDK keytool utility.

To create the key enter the following command:


keytool -genkey -keystore "keystore file" -keyalg RSA –alias machinename


This command will prompt for information about the certificate and for passwords to protect both the keystore and the keys within it. The only mandatory response is to provide the hostname from the URL of the Rational Change server. By default Rational Change 5.2 is setup to use the machine's IP address for the hostname in generated URLs. If the generated links use 192.168.10.10 then this is what should be entered at the "first and last name" prompt. This is done so that the key is issued to the URL of the website, which will stop browsers from complaining that the key and site name do not match. For example:


For Jetty: keytool -genkey -keystore "$CHANGE_HOME\jetty\rc.keystore" -alias angler -keyalg RSA
For WASCE: keytool -genkey -keystore "$WASCE_HOME\var\security\keystores\rc.keystore" -alias angler -keyalg RSA

Enter keystore password:  choose a password
What is your first and last name?
 [Unknown]:  192.168.10.10
What is the name of your organizational unit?
 [Unknown]:  Development
What is the name of your organization?
 [Unknown]:  Rational
What is the name of your City or Locality?
 [Unknown]:  
What is the name of your State or Province?
 [Unknown]:  
What is the two-letter country code for this unit?
 [Unknown]:  
Is CN=192.168.10.10, OU=Development, O=Rational, L=Unknown, ST=Unknown, C=Unknown correct?
 [no]:  yes


Enter key password for
(RETURN if same as keystore password): choose a password

Key generation using 'ikeyman' tool for WAS:

1. Open a command prompt and go to WAS-HOME/bin. Type ikeyman and enter.
   It will open ikeyman application using which keystore files can be generated.


2. Go to Key Database File>New. Select JKS as the type, type-in 'rc-keystore.jks'
   in the File Name field. Browse to a desired location and save.


3. Enter password for the file.


4. Select Personal Certificate under Key Database content and click New Self-Signed.


5. Enter hostname as Key Label (it is the Alias).


6. Common name can be IP address.


7. Organization: Rational


8. Organization Unit: Development


9. You can either enter some values to the rest of the fields or skip them as you wish.
   

1. Change directory to $CHANGE_HOME/jetty/etc

2. Create a backup of your change.xml file.

3. Open the change.xml file with your favorite text editor.

4. Locate the following section in the change.xml file:


<Call name="addListener">
  <Arg>
     <New class="org.mortbay.http.SocketListener">
        <Set name="Port">%PORT%</Set>
        <Set name="MinThreads">5</Set>
        <Set name="MaxThreads">255</Set>
        <Set name="MaxIdleTimeMs">60000</Set>
     </New>
   </Arg>
</Call>


Note that the port number in this example may not match the port number that you selected to use during your Rational Change installation.

5. Replace the above section with the following section:


<Call name="addListener">
  <Arg>
     <New class="org.mortbay.http.ibmjsse.IbmJsseListener">
        <Set name="Port">8600</Set>
        <Set name="MinThreads">5</Set>
        <Set name="MaxThreads">255</Set>
        <Set name="MaxIdleTimeMs">60000</Set>
        <Set name="LowResourcePersistTimeMs">5000</Set>
        <Set name="Keystore">$CHANGE_HOME\jetty\rc.keystore</Set>
 <Set name="Password">password</Set>
 <Set name="KeyPassword">password</Set>
     </New>
  </Arg>
</Call>


Prior to Change 5.1, the value of the class attribute was org.mortbay.http.SunJsseListener for all OSes except AIX.

The following values were used when creating your key.

• keystore – The location of the .keystore file.
• Password – The password used to access the keystore
• KeyPassword – The password used to access the key inside of the keystore

6. Change directory to $CHANGE_HOME/jetty/webapps/$CONTEXT_NAME/WEB-INF

7. Create a backup of your web.xml file.

8. Open the web.xml file with your favorite text editor.

9. Locate the following section in the web.xml file:


<context-param>
  <param-name>protocol</param-name>
  <param-value>http</param-value>
</context-param>
<context-param>
  <param-name>port</param-name>
  <param-value>8600</param-value>
</context-param>


10. Change http to https

11. Change the port number if necessary.

12. If the platform is Solaris, open $CHANGE_HOME/jetty/bin/jetty.sh in a text editor and change line 437 from


JAVA_OPTIONS="-Djetty.home=$JETTY_HOME -Djetty.log=$JETTY_LOG -Xms128m -Xmx512m -server $JAVA_OPTIONS"


to


JAVA_OPTIONS="-Djetty.home=$JETTY_HOME -Djetty.log=$JETTY_LOG -Djava.protocol.handler.pkgs=com.ibm.net.ssl.www2.protocol -Xms128m -Xmx512m -server $JAVA_OPTIONS"


If running in central server mode, all Solaris servers in your cluster must have this change applied--even servers that are not running HTTPS themselves. 13.) Stop and start the Rational Change server.

Note: Obfuscating Passwords - Jetty Server

1. Change directory to $CHANGE_HOME/jetty

2. Type in the following command replacing thePassword with your password:


java –classpath lib/org.mortbay.jetty.jar;ext/commons-logging-api.jar org.mortbay.util.Password thePassword

thepassword
OBF:1vv31w8l1v1x1yt41v1p1ym71v2p1yti1v2h1w951vu7
MD5:3c41ff681c1e3dcb68b4d8573bf1c74c



3. 3 lines of output will be printed, one starting with OBF and another starting with MD5. Copy the entire line starting with OBF and replace the password in change.xml with the password you just obfuscated.

4. If you have different passwords for the storepass and keyPassword, run through these steps for both of them if you want them both to be obfuscated.

Changes to WASCE

1. Login to Administrative Console, Click Web Servers -> Tomcat BIO HTTPS Connector. Edit the below fields:


uniqueName: User defined Unique name
address: Give the hostname where WASCE is running.
keystoreFile: var/security/keystores/rc.keystore.
port: 8400 or which ever is available.
algorithm: select Default.
keystorePass: Keystore file password (password given while generating the keystore above)
keystoreType: select JKS.
sslProtocol: select SSL.
truststoreType: select JKS.


Save it. This will create a new Tomcat BIO https connector.

2. Locate the following section in the web.xml file:


<context-param>
  <param-name>protocol</param-name>
  <param-value>http</param-value>
</context-param>
<context-param>
  <param-name>port</param-name>
  <param-value>8080</param-value>
</context-param>


3. Change http to https and port to 8400 or as given above for new Tomcat connector.

4. Restart WASCE.

Allowing a Remote Server to connect to a Central Server running HTTPS and vice-versa (for Jetty and WASCE)

In Change 5.0 and after, central and remote servers communicate via HTTP. If one of the servers is running HTTPS, then the Java installation which services the other server needs to know about it because the certificate it is being sent needs to be one that Java will automatically trust. There is no user interaction to accept the certificate like in a browser.

1. Export the certificate from the keystore generated above.


keytool -export -keystore "keystore file" -alias machinename -file "temporary file"


For our example, this would look like this:

For Jetty:
keytool -export -keystore $CHANGE_HOME\jetty\rc.keystore -alias angler -file d:\temp\change8600.cer

For WASCE:
keytool -export -keystore <WASCE_HOME>\var\security\keystores\rc.keystore -alias angler -file d:\temp\change8600.cer


Enter keystore password: (your keystore password)
Certificate stored in file <d:\temp\change8600.cer>

2. Copy your .cer file created in the previous step to the machine where your other Rational Change server is running.

3. Change directory to $JAVA_HOME/jre/bin

4. Import the certificate into Java's trusted certificate keystore.


keytool -import -alias machinename -file "The .cer file" -keystore "a keystore file"


For our purposes we want to use the .cer we copied from our other installation and we want to use Java's trusted certificate file for the keystore, $JAVA_HOME\jre\lib\security\cacerts. This keystore has a default password of changeit.


keytool -import -alias angler -file d:\temp\change8600.cer -keystore $JAVA_HOME\jre\lib\security\cacerts

Enter keystore password:  changeit
Owner: CN=192.168.10.10, OU=Development, O=Rational, L=Irvine, ST=Ca, C=US
Issuer: CN=192.168.10.10, OU=Development, O=Rational, L=Irvine, ST=Ca, C=US
Serial number: 47e7e301
Valid from: Mon Mar 24 10:21:05 PDT 2008 until: Sun Jun 22 10:21:05 PDT 2008
Certificate fingerprints:
        MD5:  5E:B9:05:C0:6E:4D:3F:10:AE:C2:CC:D3:68:29:BC:80
        SHA1: F9:2E:FD:94:F9:6C:E6:B3:82:83:35:52:E4:3B:0B:CB:70:35:19:1A
Trust this certificate? [no]:  y
Certificate was added to keystore


If the first and last name of the keystore as created in step 2 above does not match how the two Change servers are configured then there will be a lot of warnings in the event.log.

For example, if a remote server is registered to a central server using the short host name angler instead of how the keystore was created with the IP address, the log will be filled with the following warnings.


WARN: HTTPS URL host 'angler' does not match '192.168.10.10'


Although the system will still function correctly, the log will be cluttered with useless warning messages.

Changes to WAS

I) Create a Keystore in WAS

1. Copy the newly created keystore file using ikeyman tool (rc-keystore.jks) in the following folder:
   D:\IBM\WebSphere\AppServer\profiles\<Your Profile>\config\cells\<your Cell>\nodes\<your Node>.
   You can see some file with .p12 extension at this location.


2. Login to admin console and go to Security >SSL certificate and key management > Key stores and certificates.


3. Click ‘New’ and enter a name such as IBM-Rational-Change-Keystore and Description.


4. Enter the path to the newly created keystore file. The path can be given as follows:

• ${CONFIG_ROOT}/cells/<Your Cell>/nodes/<Your Node>/rc-keystore.jks.



1. Enter the password of the keystore file (twice)




2. Select Type as JKS.




3. Select Initialize at startup




4. Apply and Save.




5. Open the newly created Keystore and click on Personal Certificate. Your self-signed certificate can be found there.

1. Go to Security->SSL certificate and key management > SSL configurations


2. Click New, Enter a name, for ex. Rational-SSL-Config


3. Select NodeDefautlTrustStore as the Trust store Name


4. Select newly created Keystore as the Keystore name: (for ex.: IBM-Rational-Change-Keystore)


5. Click on the Get certificate Aliases. It will load the alias from the keystore to the drop down list below


6. Select the loaded alias for both the drop down lists.


7. Apply and Save.


8. Go back to SSL configurations, click on the newly created SSL config.


9. Click on Quality of protection (QoP) settings under Additional Properties


10. Select SSL as the Protocol, Apply and Save.


11. Go to SSL certificate and key management> Manage endpoint security configurations


12. Expand Inbound>[yourCell]>nodes>[your Node]>Servers>[your server] >


13. Click on WC_defaulthost_secure. (It uses port 9443)


14. Under Specific SSL configuration for this endpoint click Override inherited values


15. Select the newly created SSL configuration (for ex. Rational-SSL-Config) and Click Update Certificate Alias list


16. Select the alias for Certificate alias in key store.


17. Apply and Save.
    

1. Install Change on WAS.
2. Go to <WAS-HOME>\profiles\<Your Profile>\config\cells\<Your Cell>\applications\<change-context-value>.ear\deployments\
<change-context-value>\\<change-context-value>.war\WEB-INF.
3. Open web.xml and change Locate the following section in the web.xml file:

        <context-param>
          <param-name>protocol</param-name>
          <param-value>http</param-value>
       </context-param>
       <context-param>
          <param-name>port</param-name>
          <param-value>8600</param-value>
       </context-param>

4. Modify the protocol to https and port to 9443 (whichever be your secure port), save and close.
5. Restart WAS.

Allowing a Remote Server to connect to a Central Server running HTTPS and vice-versa on WAS

1. Login to WAS admin console and go to Security>SSL certificate and key management > Key stores and certificates
2. Click NodeDefaultTrustStore.
3. Click Signer certificates
4. Click Retrieve from port
5. Enter the hostname and port of the other server on the respective fields.
6. Select NodeDefaultSSLSettings as SSL configuration for outbound connection
7. Enter the hostname of the other server as Alias and Click Retrieve signer information button.
8. Apply and Save.
9. Do the same setting on the other WAS server.
10. In case both central and remote servers are running on the same WAS server, follow the above steps to retrieve signer certificate from its keystore to its own trust store. Enter hostname and secure port of the same server, give hostname of the same server as the alias and click retrieve.