White Paper: Configuring SSL Communication between IBM HTTP Server and the Tivoli Common Agent

White Paper: Configuring SSL Communication between IBM HTTP Server and the Tivoli Common Agent IBM Tivoli Provisioning Manager Version 7.2.1 Document version 0.1 Lewis Lo IBM Tivoli Provisioning Manager, Continuous Engineering lewisl@ca.ibm.com

Copyright International Business Machines Corporation 2011. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Tivoli Provisioning Manager CONTENTS Revision History... iv Configuring SSL communication between IBM HTTP Server and the Tivoli Common Agent...1 Configuring the keystore in the IBM HTTP Server environment...2 Creating a CMS keystore for IBM HTTP Server... 2 Creating the certificate request... 5 Generating a certificate from the AM signer certificate... 6 Adding the signed certificate to the IBM HTTP Server CMS keystore... 6 Testing Tivoli Common Agent and IBM HTTP Server SSL communication... 9 Appendix A: Using a corporate signer certificate for IBM HTTP Server and Tivoli Common Agent communication...10 Distributing the corporate signer certificate to the endpoint...11 Configuring IBM HTTP Server to use a corporate signed certificate...11 Troubleshooting...12 Saving the keystore in CMS format... 12 No CARootKeyRingCMS.sth is found after the CMS keystore is created... 12 Nothing happened when receiving the certificate into the CMS keystore after generating the signed certificate... 12 Password for CARootKeyRing.jks cannot be found... 12

IBM Tivoli Provisioning Manager Version 7.2.1 REVISION HISTORY Date Version Revised By Comments 2011-11-25 0.1 LL Initial document iv

Configuring SSL communication between IBM HTTP Server and the Tivoli Common Agent Configuring SSL communication between IBM HTTP Server and the Tivoli Common Agent This document describes how to setup Secure Sockets Layer (SSL) communication between IBM HTTP Server and Tivoli Common Agent without updating any file in the Tivoli Common Agent endpoint. This communication is configured using the existing Tivoli Common Agent certificates framework. The SSL communication is initiated from the Tivoli Common Agent endpoint. Hence, IBM HTTP Server must present a certificate to the endpoint and the endpoint must accept it. In the Tivoli Common Agent SSL framework, all certificates are generated internally. There are no third party Common Agent certificates involved in the transaction. This procedure includes the following tasks; Creating a Java-based content management system (CMS) -provider keystore for IBM HTTP Server Creating certificate request Generating the certificate from the Agent Manager (AM) signer certificate Generating the certificate from the AM signer certificate Adding the signed certificate into IBM HTTP Server CMS keystore Testing the Tivoli Common Agent and IBM HTTP Server SSL communication Figure 1 - AM signer certificate in SSL communication 1

Configuring SSL communication between IBM HTTP Server and the Tivoli Common Agent To configure this specific environment, the following tools are required: - ikeyman/gskit: you can use the one shipped with IBM HTTP Server - keytool from Java JDK - openssl from www.openssl.com Configuring the keystore in the IBM HTTP Server environment The keystore used in this environment has the following characteristics: - CMS keystore - A password stash file must be created for the keystore - The keystore contains: o A signer certificate from the agent manager root key ring o A certificated signed by the signer certificate Creating a CMS keystore for IBM HTTP Server The current version of IBM HTTP Server being tested is IBM HTTP Server 7.0.0.0. To create the keystore, perform the following steps: 1. Copy the CARootKeyRing.jks from the agent manager into the IBM HTTP Server. The CARootKeyRing.jks is located in %TIO_HOME%\..\..\AgentManager\certs. You might need a password to open the file. 2. Open a ikeyman/gskit in the IBM HTTP Server. In Windows, it can be launched from C:\Program Files\ibm\HTTPServer\bin\ikeyman. 3. Open the CARootKeyRing.jks that is copied from Agent Manager. Enter the password when prompted. 4. Under Signer Certificates, make sure that a rootcert is there. 2

Configuring SSL communication between IBM HTTP Server and the Tivoli Common Agent 5. Under Personal certificates, make sure that a rootkey is there. Click View/Edit. You see a screen similar to the following: Because it is a signer certificate, Issued to and Issued by refer to the same entity. 6. Close the CARootKeytRing.jks and launch the ikeyman/gskit again. 7. Create a new CMS keystore. Click Key Database File > New. In Key database type, select CMS. Enter the file name and its location. 3

Configuring SSL communication between IBM HTTP Server and the Tivoli Common Agent 8. Specify a password and select Stash password to a file. 9. Import the key into this new keystore. Under Personal Certificates, click Import and specify the information to open the CARootKeyRing.jks. The Key file type is specified as JKS. 10. Enter the password when prompted. 11. You are prompted to select the key that you want to import. If there is a list, select the rootkey as follows: 12. In the Change Labels panel, click OK. 13. The imported key is shown in Personal Certificates. Exit ikeyman/gskit. 4

Configuring SSL communication between IBM HTTP Server and the Tivoli Common Agent 14. In the directory where the new keystore is saved, the following files are required to configure SSL in IBM HTTP Server: - CARootKeyRingCMS.sth - CARootKeyRingCMS.rdb - CARootKeyRingCMS.kdb Creating the certificate request 1. Open the CMS keystore that was just created for IBM HTTP Server, for example CARootKeyRingCMS.kdb. 2. Select Personal Certificate Requests from the list and click New. 3. Enter the Key Label, Key Size and Signature Algorithm. Make sure the Common Name field has the hostname of the IBM HTTP Server. The rest of the fields are optional. In this example, the Key Label has a value of IHS_Cert and the request is created as certreq.arm. 4. When you receive a message stating that the request needs to send to certification authority, click OK to finish the creation of the request. 5. Exit the ikeyman/gskit. 5

Configuring SSL communication between IBM HTTP Server and the Tivoli Common Agent Generating a certificate from the AM signer certificate 1. Launch ikeyman/gskit and open the CARootKeyRing.jks. 2. Click Key Database File > Save As. Specify the Key database type as PKCS12. Specify the file name. Enter passwords when prompted. Note: In these steps you create the same keystore in another format, for example PKCS12. So, the PKCS format of keystore is saved as CARootKeyRingPKCS.p12. 3. Close ikeyman/gskit. 4. To extract the key from the new PKCS12 keystore using OpenSSL, run the following command and enter the password of the keystore when prompted. openssl pkcs12 -in CARootKeyRingPKCS.p12 -out carootkey.key -nocerts nodes A key file, carootkey.key, is created as a result of the command. 5. To extract the certificate from the CARootKeyRingPKCS.p12 file, run the following command and enter the password when prompted. openssl pkcs12 -in CARootKeyRingPKCS.p12 -out caroot.crt -nokeys nodes A certificate file, caroot.crt, is created as a result of the command. 6. To generate a new certificate with the signer certificate caroot.crt with key carootkey.key, run the following command; openssl x509 -req -days 365 -in certreq.arm -CA caroot.crt -CAkey carootkey.key -CAcreateserial -out newcert.crt A new certificate that is signed by caroot.crt with key carootkey.key is generated as newcert.crt based on the request certreq.arm. A certificate newcert.crt is generated and signed by the agent manager signer certificate. Adding the signed certificate to the IBM HTTP Server CMS keystore 1. Open the CMS keystore, for example, CARootKeyRingCMS.kdb, using ikeyman/gskit. 2. Under Personal Certificates, select Receive. You might need to select All Files for the Files of Type to get the newcert.crt listed in the panel. 6

Configuring SSL communication between IBM HTTP Server and the Tivoli Common Agent 3. When prompted Do you want to set the key as the default key in the database, click Yes. You might see two certificates with the same label displayed in the panel: 7

Configuring SSL communication between IBM HTTP Server and the Tivoli Common Agent 4. Click either of the IHS_Cert files and click View/Edit. You see the following screen: Issued to and Issued by are different now. Issued by is the entity from the signer cert, whereas Issued to is the entity that created the request before. Under Personal Certificate Requests, an empty list is displayed because you have accepted the generated certificate which satisfies the request. The CMS keystore is now ready to be used by IBM HTTP Server SSL communication. Before enabling SSL in IBM HTTP Server, make sure that it is working without SSL,for example, http://<ihs_hostname>. To enable SSL in IBM HTTP Server, download the following instructions and see the SSL content in Chapter 12. ftp://public.dhe.ibm.com/software/webserver/appserv/library/v70/ihs_70.pdf After it is enabled, you can launch the IBM HTTP Server page via the SSL port, for example, https://<ihs_hostname>. 8

Configuring SSL communication between IBM HTTP Server and the Tivoli Common Agent Testing Tivoli Common Agent and IBM HTTP Server SSL communication Before testing the SSL communication, test the non-ssl communication. Test the Tivoli Common Agent and IBM HTTP Server via non-ssl communication - Make sure that the non-ssl communication with IBM HTTP Server is functioning and launches with no error, for example http://<ihs_hostname>. - On the Tivoli Common Agent endpoint, run the following command which results in the creation of the file, test.gif. C:\Program Files (x86)\tivoli\ep\runtime\agent\bin>agentcli.bat filemgr agent copyto. test.gif http://ihs_hostname/images/administration.gif - Ensure that there are no errors. Test the Tivoli Common Agent and IBM HTTP Server via SSL communication - Make sure that the SSL communication with IBM HTTP Server is functioning and launches with no error, for example, https://<ihs_hostname>. - On the Tivoli Common Agent endpoint, run the following command which results in the creation of the file, test.gif. C:\Program Files (x86)\tivoli\ep\runtime\agent\bin>agentcli.bat filemgr agent copyto. test.gif https://ihs_hostname/images/administration.gif - Ensure that there are no errors. 9

Appendix A: Using a corporate signer certificate for IBM HTTP Server and Tivoli Common Agent communication Appendix A: Using a corporate signer certificate for IBM HTTP Server and Tivoli Common Agent communication In an enterprise solution, corporate might create a signer certificate and all the signed certificates for SSL communications. This solution is depicted in the following diagram. Figure 2 - SSL solution with corporate signer certificate To use a corporate signer and signed certificate in the SSL communication, you must perform the following tasks: Copy the corporate signer certificate to the endpoint, for example, agenttrust.jks. Configure IBM HTTP Server to use a corporate signed certificate. 10

Appendix A: Using a corporate signer certificate for IBM HTTP Server and Tivoli Common Agent communication Distributing the corporate signer certificate to the endpoint It is not always possible for you to update every endpoint after deployment with its own corporate signer certificate, especially when there are hundreds of endpoints in the enterprise. To deliver a signer certificate automatically to an endpoint during deployment, edit the agenttrust.jks in the Agent Manager environment before the deployment of the Tivoli Common Agent to the endpoint. Perform the following steps: 1. Prepare the signer certificate for the SSL communication. 2. Add the corporate signer certificate in $TIO_HOME/repository/tivoli/TCA/agentTrust.jks. 3. Install the Tivoli Common Agent to the endpoint as usual. After the Tivoli Common Agent is installed successfully, the corporate signer certificate is copied with the agenttrust.jks to the endpoint. Tivoli Provisioning Manager is not responsible for the corporate signer certificate in the agenttrust.jks. It is your responsibility to keep track the expiry date and the validity of the certificate. Configuring IBM HTTP Server to use a corporate signed certificate The procedure for creating a signed certificate is different between companies. All that is required is to make sure that the certificate is signed by the corporate signer certificate, and the certificate is imported and configured in an IBM HTTP Server environment. Once the SSL communication with this signed certificate is configured in an IBM HTTP Server, the Tivoli Common Agent can communication with the IBM HTTP Server using the corporate SSL solution with its own Certificate Authority, signer certificates, and signed certificates. 11

Troubleshooting Troubleshooting During the configuration, creation, and generation of the signer and signed certificate, you may encounter errors. This section describes some of these errors and their solutions. Saving the keystore in CMS format Issue: When saving the keystore in CMS format, you get the following error: Solution: You are saving the existing keystore in a CMS format, as described in the section Creating a CMS keystore for IBM HTTP Server. You must create a new CMS format keystore and import the key into the CMS keystore instead. No CARootKeyRingCMS.sth is found after the CMS keystore is created Issue: After the CMS keystore is created, only the kdb keystore file, CARootKeyRingCMS.kdb, is found. Solution: When creating the CMS keystore, make sure that Stash password to a file is selected. Nothing happened when receiving the certificate into the CMS keystore after generating the signed certificate Issue: Nothing happens when receiving a certificate into the CMS keystore. The request in the Personal Certificate Requests panel still shows the certificate request. Solution: You are importing the root certificate, caroot.crt, exported from the carootkeyring. You must import the signed generated certificate, newcert.crt, instead. Password for CARootKeyRing.jks cannot be found Issue: The password in the pwd file for CARootKeyRing.jks cannot be decrypted, and so CARootKeyRing.jks cannot be opened. Solution: Contact the service team. The Common Agent Services team can provide the password for the CARootKeyRing.jks. 12

IBM Tivoli Provisioning Manager Version 7.2.1 Copyright IBM Corporation 2011 IBM United States of America Produced in the United States of America US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. 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 PAPER 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 may be made periodically to the information herein; these changes may be incorporated in subsequent versions of the paper. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this paper at any time without notice. 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. Any references in this document 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. 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 is for planning purposes only. The information herein is subject to change before the products described become available. If you are viewing this information softcopy, the photographs and color illustrations may not appear. 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. 13

Trademarks IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. If these and other IBM trademarked terms are marked on their first occurrence in this information with a trademark symbol ( or ), these symbols indicate U.S. 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 "Copyright and trademark information" at http://www.ibm.com/legal/copytrade.shtml. Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo, Celeron, Intel Xeon, Intel SpeedStep, Itanium, and Pentium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates. AMD or registered trademarks of Advanced Micro Devices Corporation or its subsidiaries in the United States and other countries. VMware or registered trademarks of VMware or its subsidiaries in the United States and other countries. 14