Configuring IBM Rational Synergy to use HTTPS Protocol

Technical Note Configuring IBM Rational Synergy to use HTTPS Protocol November 20, 2013 This edition applies to IBM Rational Synergy version 7.1, and to all subsequent releases and modifications until otherwise indicated in new editions. Before using this information, be sure to read the general information under Appendix: Notices on page 8. US Government Users Restricted Rights Use, duplication, or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Page 1 of 10

Table of Contents Introduction... 3 Create an SSL certificate... 3 Sign the certificate (optional)... 4 Configure the CCM Server... 5 Configure the Clients... 6 Export the server certificate... 6 Add the certificate to the clients... 6 Appendix: Notices... 8 Trademarks... 10 Page 2 of 10

Introduction This document describes how to configure Synergy to use the HTTPS protocol for secure network communication between the client and server. With HTTPS, the Secure Socket Layer (SSL) is used to encrypt the HTTP data stream between the client and web server. The technique described in this paper applies to the Synergy Admin client and Web Mode clients only. Configuring Synergy to communicate using the HTTPS protocol involves three steps: Create an SSL certificate Configure the CCM server Configure Clients Each of these steps is described in detail in the following sections. Create an SSL certificate To prepare the CCM server to accept HTTPS connections, the administrator must create a SSL certificate for the web server. The easiest way to create a SSL certificate is to use the keytool utility to create a selfsigned certificate. The keytool utility is a Key and Certificate Management Tool that manages a keystore (database) of keys and certificates. Here are the steps to create a self-signed certificate using the keytool utility on UNIX. You must create the certificate while logged in as the ccm_root user. % su ccm_root % cd $CCM_HOME/jre/bin % keytool -genkey -keyalg RSA keysize 2048 -keystore my_server.keystore -alias jettykey -validity 720 Enter keystore password: password Re-enter keystore password: password What is your first and last name? [Unknown]: <server host name> What is the name of your organizational unit? [Unknown]: <optional> What is the name of your organization? [Unknown]: <optional> What is the name of your City or Locality? [Unknown]: <optional> Page 3 of 10

What is the name of your State or Province? [Unknown]: <optional> What is the two-letter country code for this unit? [Unknown]: <optional> Is CN=<server host name>, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown correct? [no]: y Enter key password for <jettykey> (RETURN if same as keystore password): Note: In order to avoid warnings when the web browser connects to the server, the first and last name field should be the same as the hostname field in the URL (i.e. https://<hostname>:8400) that will be used to connect to the server. The -validity argument enables you to specify the number of days the certificate will be valid. If not specified, the default value is 90, meaning the certificate would expire in 90 days. The example above uses the value 720, which is approximately 2 years. Use a setting that is appropriate for your organization. For more information about the keytool utility provided by the IBM Java Runtime Environment 6.0, bundled with Synergy, see the following article. http://www.ibm.com/developerworks/java/jdk/security/60/secguides/keytooldocs/keytool.html Sign the certificate (optional) Most web browsers will give a warning if the certificate is not signed by a trusted Certification Authority (CA) such as VeriSign. In order to avoid such warnings, the certificate needs to be signed by a trusted CA. Here are the steps to submit and receive a signed certificate: Generate a certificate signing request (CSR) % keytool -certreq -keystore my_server.keystore -alias jettykey -file jetty.csr Enter keystore password: password Enter key password for <jettykey>: password Submit the CSR to a trusted certificate authority Send the certificate signing request (CSR) that you just generated to a certificate authority (CA) that you trust. This could be a commercial CA whose signatures most or all modern browsers will honor or a CA that is internal to your organization and whose public key is installed into all browsers on your organization's computers. The specifics of this step are outside the scope of this article. Page 4 of 10

Import the signed certificate After you submit the certificate signing request to the CA, and fulfill the CA's requirements for validating your identity and trustworthiness, the CA will send you a certificate file that bears the CA's signature. Import the signed certificate into the keystore that you created using following commands: % keytool -importcert -trustcacerts -keystore my_server.keystore -alias trsutedca -file ca-csr.txt Enter keystore password: password % keytool -import -keystore my_server.keystore -alias jettykey -file signedcsr.txt Enter keystore password: password Configure the CCM Server 1. Copy the keystore file to $CCM_HOME/jetty/etc/keystores directory % cp my_server.keystore $CCM_HOME/jetty/etc/keystores 2. Change the passwords in the $CCM_HOME/jetty/etc/cm_https.xml file. For Synergy 7.1.0.6 and subsequent 7.1 Fix Packs and Interim Fixes, change both the "KeyStorePassword" and "KeyManagerPassword" fields if you used a password other than the default. For all other releases, change both the "Password" and "KeyPassword" fields if you used a password other than the default. The file cm_https.xml contains a clear text password for the jetty keystore. Ensure that it is readable by the ccm_root user, and apply proper permissions to secure it from being read or modified by users other than ccm_root. Note: If you want to set up multiple HTTPS servers, you can use a different keystore for each server, but all keystores must share the same key and keystore passwords. From Rational Synergy 7.2.1 onwards, it supports TLSv1.2 protocol. To start CCM Server with TLSv1.2 protocol, uncomment the following statement in cm_https.xml <-- <Set name= protocol >TLSv1.2</Set> --> Note: By default, the above statement is commented and CCM server will start with default SSL protocol SSLv3 Page 5 of 10

3. Modify $CCM_HOME/etc/ccm.server.properties file to change the server protocol and assign the keystores to the server. a. Change the default protocol for all servers, or create a new entry for the specific server that will use HTTPS protocol. For example: cm.webserver.default.protocol = https or cm.webserver.my_server.protocol = https b. Create a new keystore entry that references the keystore file you copied into the keystores directory in step 1 above. For example: cm.webserver.my_server.https.keystore = my_server.keystore 4. Test the server HTTPS settings from a web browser. a. Start the server % ccm_server -start b. Open a web browser and visit the new server URL address (https://<server>:<port>). The web browser may ask you if you want to trust the certificates from the server. Answer yes and you should see the page containing the Synergy Windows client download information. Configure the Clients Export the server certificate % su ccm_root % cd $CCM_HOME/jre/bin % keytool -export -keystore $CCM_HOME/jetty/etc/keystores/my_server.keystore - alias jettykey -file my_server.cer Enter keystore password: password Certificate stored in file <my_server.cer> Add the certificate to the clients Copy the my_server.cer file to each client system where the user will run the Synergy Web Mode session, and import it to the local keystore. Page 6 of 10

C:> cd %CCM_HOME%\jre\bin C:> keytool -import -alias usir-sol2 -file my_server.cer -keystore..\lib\security\cacerts Enter keystore password: changeit Owner: CN=my_server, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown Issuer: CN=my_server, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown Serial number: 49d2466b Valid from: 3/31/09 9:35 AM until: 6/29/09 9:35 AM Certificate fingerprints: MD5: F6:3F:8C:18:0B:0C:DB:22:0C:51:0B:B3:4B:41:40:27 SHA1: CE:6C:B6:99:52:4D:66:1E:B4:48:94:4D:0A:7B:88:EE:CF:F7:68:B4 Trust this certificate? [no]: y Certificate was added to keystore Note: The default password of the JRE keystore is changeit. It can be changed using the keytool -storepasswd command. The above steps need to be applied to every Synergy client installation that will connect to the server. Then Synergy sessions on those clients can be started using the https server URL. Page 7 of 10

Appendix: Notices This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-ibm product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send written license inquiries to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. For license inquiries regarding double-byte character set (DBCS) information, contact the IBM Intellectual Property Department in your country or send written inquiries to: IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome, Minato-ku Tokyo 106-0032, Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EX- PRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WAR- RANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions. Therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Page 8 of 10

Any references in this information to non-ibm Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: Intellectual Property Dept. for Rational Software IBM Corporation 1 Rogers Street Cambridge, Massachusetts 02142 U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us. Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment. Information concerning non-ibm products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-ibm products. Questions on the capabilities of non-ibm products should be addressed to the suppliers of those products. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. Page 9 of 10

Trademarks IBM, the IBM logo, AIX, and Rational are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. These and other IBM trademarked terms are marked on their first occurrence in this information with the appropriate symbol ( or ), indicating US registered or common law trademarks owned by IBM at the time this information was published. Such trademarks may also be registered or common law trademarks in other countries. A current list of IBM trademarks is available on the Web at www.ibm.com/legal/copytrade.html. Windows is a trademark of Microsoft Corporation in the United States, other countries, or both. Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both. Solaris, Java, and all Java-based trademarks and logos are trademarks of Oracle Corporation in the United States, other countries, or both. HP-UX is a trademark of Hewlett-Packard Company in the United States, other countries, or both. Pentium is a trademark of Intel Corporation in the United States, other countries, or both. Other company, product or service names mentioned may be trademarks or service marks of others. Page 10 of 10