IBM i2 Analyze: Configuring Secure Sockets Layer (SSL) Version 4 Release 1 IBM SC27-5091-00
Note Before using this information and the product it supports, read the information in Notices on page 15. This edition applies to version 4, release 1, modification 1 of IBM i2 Analyze (product number 5725-G22) and to all subsequent releases and modifications until otherwise indicated in new editions. Copyright IBM Corporation 2015, 2016. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Contents Chapter 1. About this guide...... 1 Chapter 2. Contacting IBM support... 3 Chapter 3. Configuring trust between the client and the HTTP server...... 5 Creating a keystore and certificate....... 5 Installing a certificate on client workstations.... 6 Chapter 4. Securing the connection between the client and the HTTP server. 7 Configuring SSL on i2 Analyze........ 7 Configuring WebSphere Application Server Liberty profile................ 10 Chapter 6. Testing the deployment... 13 Connecting to the Intelligence Portal...... 13 Connecting to the Analysis Repository from Analyst's Notebook Premium........ 13 Notices.............. 15 Trademarks.............. 17 Chapter 5. Securing the connection between the HTTP server and WebSphere Application Server Liberty profile............... 9 Configuring the IBM HTTP Server....... 9 Copyright IBM Corp. 2015, 2016 iii
iv IBM i2 Analyze: Configuring Secure Sockets Layer (SSL)
Chapter 1. About this guide This guide describes an example approach to enabling SSL on i2 Analyze. The instructions assume that i2 Analyze is deployed, and working correctly. The instructions are suitable for deployments of i2 Analyze on Windows and Linux. The guide uses Windows file paths, for Linux deployments you must change the file paths for your operating system. The instructions use self-signed certificates to demonstrate an SSL connection, in a production deployment you must use certificates that are signed by a trusted certificate authority. You should also refer to the documentation for IBM WebSphere Application Server Liberty profile and IBM HTTP Server. The guide is not intended to provide instructions for managing keystores, or certificates. Attention: While IBM takes reasonable steps to verify the suitability of i2 Analyze for Internet deployment. It does not address lower-level issues such as guarding networks against penetration, firewall configurations to avoid DoS or DDoS attacks, load balancing and the like. For a deployment of i2 Analyze, follow industry-standard practices and recommendations for protection of your systems. IBM accepts no liability for the consequences of such attacks on your systems. Intended audience This guide is intended for readers who are familiar with managing keystores and certificates, securing network connections, and the i2 Analyze configuration. Copyright IBM Corp. 2015, 2016 1
2 IBM i2 Analyze: Configuring Secure Sockets Layer (SSL)
Chapter 2. Contacting IBM support IBM Support provides assistance with product defects, answers FAQs, and helps users to resolve problems with the product. About this task After trying to find your answer or solution by using other self-help options such as technotes, you can contact IBM Support. Before contacting IBM Support, your company or organization must have an active IBM software subscription and support contract, and you must be authorized to submit problems to IBM. For information about the types of available support, see the Support portfolio topic in the Software Support Handbook. Procedure To contact IBM Support about a problem: 1. Define the problem, gather background information, and determine the severity of the problem. For more information, see the Getting IBM Support topic in the Software Support Handbook. 2. Gather diagnostic information. 3. Submit the problem to IBM Support in one of the following ways: a. Online through the IBM Support Portal at http://www.ibm.com/software/ support. You can open, update, and view all of your service requests from the Service Request portlet on the Service Request page. b. By phone: For the phone number to call in your region, see the Directory of worldwide contacts web page at http://www.ibm.com/planetwide Results If the problem that you submit is for a software defect or for missing or inaccurate documentation, IBM Support creates an Authorized Program Analysis Report (APAR). The APAR describes the problem in detail. Whenever possible, IBM Support provides a workaround that you can implement until the APAR is resolved and a fix is delivered. IBM publishes resolved APARs on the IBM Support website daily, so that other users who experience the same problem can benefit from the same resolution. Copyright IBM Corp. 2015, 2016 3
4 IBM i2 Analyze: Configuring Secure Sockets Layer (SSL)
Chapter 3. Configuring trust between the client and the HTTP server To connect to i2 Analyze by using SSL, the client workstation must trust the HTTP server. This trust is established through a certificate that is shared between the HTTP server and the client workstation. About this task Use the IBM Key Management tool to create a keystore and certificate for the HTTP server. Then, install the certificate on the client workstation. Creating a keystore and certificate A keystore contains any certificates that are associated with the HTTP server. In a test environment, create a self-signed certificate to demonstrate SSL communication. Procedure 1. Open the IBM Key Management tool. Navigate to the IBM\HTTPServer\bin directory, and run ikeyman. Note: The IBM Key Management tool uses a GUI or Window Manager. If you do not have a GUI or Window Manager on your system, you can use the command line interface. For more information on the command line interface, see Key Management Utility command-line interface (gskcmd) syntax in IBM Knowledge Center. 2. Create a keystore. a. Click Key Database File > New. b. Ensure that Key database type is set to CMS. c. Set the File Name to i2_key.kdb. d. Set the Location to the directory that contains the toolkit. For example, C:\IBM\i2analyze. e. Click OK. f. In the Password Prompt window, enter a password for the key database. Then, select the Stash password to a file check box and click OK. The key database and password stash file are created, and the key database is opened in the IBM Key Management tool. 3. Create a certificate. a. Click New Self-Signed. b. Set the Key Label to i2 Certificate. c. Ensure that the value of Common Name is set to the host name of the server that hosts the HTTP server. Important: The URL that you use to connect to i2 Analyze must use the same value for the host name as the value of Common Name. Note: The rest of the settings can be left for this example. d. Click OK. Copyright IBM Corp. 2015, 2016 5
4. Extract the i2 Certificate certificate. a. Click Extract Certificate. b. From the Data type list, select Binary DER data. c. Set the Certificate file name to i2_certificate.der. d. Ensure that Location is set to the same location as the keystore. e. Click OK. 5. Close the IBM Key Management tool. Installing a certificate on client workstations To enable SSL connection to i2 Analyze, the extracted certificate must be installed, and trusted, on each client workstation. About this task The following steps must be completed on any Windows client that needs to connect by using SSL. Note: To install the certificate on Linux workstations, see the documentation for your operating system. Copy and install the i2_certificate.der file that you created in Creating a keystore and certificate on page 5, on each client workstation that is connecting by using SSL. Procedure 1. Copy the extracted i2_certificate.der file to each client workstation. 2. Install the certificate. a. Double-click the i2_certificate.der file. b. Click Install Certificate, and then click Next. c. Click Place all certificates in the following store. d. Click Browse, and select Trusted Root Certification Authorities. e. Click Next, and then click Finish. f. A security warning is displayed, because the certificate is self-signed. The operating system cannot verify the self-signed certificate. Click Yes to accept the certificate. In a production system, the certificate from the HTTP server must be signed by a trusted certificate authority. 6 IBM i2 Analyze: Configuring Secure Sockets Layer (SSL)
Chapter 4. Securing the connection between the client and the HTTP server To connect to i2 Analyze, the client connects through the HTTP server. The connection to the HTTP server can be configured to use SSL by editing the i2 Analyze configuration. About this task The following diagram shows the connection that is secured by following the instructions in this chapter: Configuring SSL on i2 Analyze By default, deployments of i2 Analyze are configured to have SSL disabled. To enable SSL, both the application and HTTP server configurations must be modified. Before you begin v The i2_key.kdb keystore file must be created according to the instructions in Creating a keystore and certificate on page 5. v Stop the IBM HTTP Server that hosts the reverse proxy. Procedure 1. Edit the http-server.properties file. a. Navigate to the toolkit\configuration\environment directory, and by using a text editor, open the http-server.properties file. b. Set the http.server.ssl.enabled property to true. c. Set the http.server.keystore.file to the location of the keystore file. For example, C:/IBM/i2analyze/i2_key.kdb. 2. Open a command prompt and navigate to the toolkit\scripts directory. Copyright IBM Corp. 2015, 2016 7
3. To deploy i2 Analyze with the edited http-server.properties file, and to install the SSL configuration on the HTTP server, run the following command: setup -t configurehttpserver Note: The httpd.conf, and plugin-cfg.xml files are updated to use the SSL configuration. Any custom rewrite rules in the httpd.conf file must be added to the <VirtualHost*:443> element. You must complete these changes each time the configurehttpserver task is run. 4. Start, or restart, the IBM HTTP Server that hosts the reverse proxy. 8 IBM i2 Analyze: Configuring Secure Sockets Layer (SSL)
Chapter 5. Securing the connection between the HTTP server and WebSphere Application Server Liberty profile The connection between the HTTP server and WebSphere Application Server Liberty profile can be secured by SSL. To secure the connection, the HTTP server and WebSphere Application Server Liberty profile must have access to the key database file, and the associated password. About this task The following diagram shows the connection between the HTTP server and WebSphere Application Server Liberty profile that is secured by following the instructions in this chapter: Configuring the IBM HTTP Server They key database file contains the certificates that are associated with the HTTP server. The plugin-cfg.xml file requires information to access the key database file. Before you begin Stop the IBM HTTP Server that hosts the reverse proxy. About this task The following steps must be completed each time the configurehttpserver task is run. Procedure 1. Navigate to the IBM\HTTPServer\plugins\iap\config directory, and by using an XML editor, open the plugin-cfg.xml. Copyright IBM Corp. 2015, 2016 9
2. Set the UseInsecure attribute of the <Config> element to false. By setting UseInsecure to false, the HTTP server allows only https connections, and does not allow http connections. In each <ServerCluster> element, there is a child <Server> element. Ensure that each <Server> element has a child <Transport> element that uses the https protocol. 3. Add the following code to any <Server> elements that do not have a child <Transport> element that uses the https protocol: <Transport Hostname="host-name" Port="9444" Protocol="https"> </Transport> 4. Add the following <Property> elements as children of the <Transport> element that uses the https protocol: <Property Name="Keyring" Value="C:/IBM/i2analyze/i2_key.kdb"/> <Property Name="Stashfile" Value="C:/IBM/i2analyze/i2_key.sth"/> Where the Value attributes contain the absolute paths to the keystore and password stash files. 5. Save, and close, the plugin-cfg.xml file. Configuring WebSphere Application Server Liberty profile The WebSphere Application Server Liberty profile server requires information about the key database file that is associated with the HTTP server. Update the server.security.xml file with the location, and password of the key database file. Procedure 1. Use the gskcmd command to convert the CMS type keystore to the Public Key Cryptography Standards #12 (PKCS12) format. a. Navigate to the IBM\HTTPServer\bin directory. b. In a command prompt, run the following command: gskcmd -keydb -convert -db C:\IBM\i2analyze\i2_key.kdb -old_format cms -new_format p12 -pw password Where the db parameter specifies the path the keystore file. The pw parameter specifies the password that is used to access the keystore database. The i2_key.p12 file is created, in the same location as the i2_key.kdb file. 2. Use the WebSphere Application Server Liberty profile securityutility command to encode the password for the keystore. a. Navigate to the bin directory of your WebSphere Application Server Liberty profile deployment that is configured by the deployment toolkit. b. In a command prompt, run the following command: securityutility encode password The encoded password is displayed in the command line. Record the encoded password, including the {xor} prefix. 3. Edit the server.security.xml file for the i2analyze server. a. Navigate to the IBM\i2analyze\deploy\wlp\usr\servers\i2analyze directory, and by using an XML editor, open the server.security.xml file. 10 IBM i2 Analyze: Configuring Secure Sockets Layer (SSL)
b. Add a <keystore> element before the closing <server> element, by using the following code: <keystore id="defaultkeystore" password="encoded_password" location="c:\ibm\i2analyze\i2_key.p12" type="pkcs12"/> Where the location attribute specifies the value to the i2_key.p12 file that is created in the first step. Note: Leave the id attribute as defaultkeystore. For information about the <keystore> element, see SSL configuration attributes in IBM Knowledge Center. 4. Redeploy i2 Analyze. Open a command prompt and navigate to the toolkit\scripts directory, then run the following command: setup -t deploy 5. Start, or restart, the IBM HTTP Server that hosts the reverse proxy. Chapter 5. Securing the connection between the HTTP server and WebSphere Application Server Liberty profile 11
12 IBM i2 Analyze: Configuring Secure Sockets Layer (SSL)
Chapter 6. Testing the deployment To ensure that the platform is using SSL, access i2 Analyze from a client workstation. Connect to the Intelligence Portal in a web browser, and to the Analysis Repository in Analyst's Notebook Premium. Before you begin v The HTTP server's certificate must be installed, and trusted, on the client workstation. For more information, see Installing a certificate on client workstations on page 6. v The application server must be running. To start the server, in a command prompt navigate to the toolkit\scripts directory and run the following command: setup -t startliberty Connecting to the Intelligence Portal To ensure that the connection is using SSL, access the Intelligence Portal from a client workstation. When the HTTPS protocol is used, the connection is secured by SSL. Procedure Open a web browser, and navigate to http://host_name/apollo (where host_name is the fully qualified domain name or IP address of the HTTP server, and matches the Common Name value of the certificate). If SSL is configured correctly, you are redirected to https://host_name/apollo. Results When you connect to the Intelligence Portal, the connection is secure. Connecting to the Analysis Repository from Analyst's Notebook Premium To ensure that the connection is using SSL, connect Analyst's Notebook Premium to the Analysis Repository on a client workstation. When the HTTPS protocol is used, the connection is secured by SSL. Procedure Open Analyst's Notebook Premium, and connect to the Analysis Repository with the following URL: https://host_name/apollo (where host_name is the fully qualified domain name or IP address of the HTTP server, and matches the Common Name value of the certificate). Note: If you try to connect using the HTTP protocol (http://host_name/apollo), you are no longer able to log in to the Analysis Repository. Results When you connect to the Analysis Repository, the connection is secure. Copyright IBM Corp. 2015, 2016 13
14 IBM i2 Analyze: Configuring Secure Sockets Layer (SSL)
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 license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. 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 EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 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. 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: IBM United Kingdom Limited Hursley House Hursley Park Winchester, Hants, SO21 2JN UK Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. Copyright IBM Corp. 2015, 2016 15
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. All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only. 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. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not be liable for any damages arising out of your use of the sample programs. If you are viewing this information softcopy, the photographs and color illustrations may not appear. 16 IBM i2 Analyze: Configuring Secure Sockets Layer (SSL)
Trademarks IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at Copyright and trademark information at www.ibm.com/legal/copytrade.shtml. Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States, and/or other countries. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners. Other company, product, and service names may be trademarks or service marks of others. Notices 17