Transcription

1 Implementing HTTPS in Contract Management July 2011

2 Copyright Oracle Primavera Implementing HTTPS in Contract Management Copyright 1996, 2011, Oracle and/or its affiliates. All rights reserved. The Programs (which include both the software and documentation) contain proprietary information; they are provided under a license agreement containing restrictions on use and disclosure and are also protected by copyright, patent, and other intellectual and industrial property laws. Reverse engineering, disassembly, or decompilation of the Programs, except to the extent required to obtain interoperability with other independently created software or as specified by law, is prohibited. The information contained in this document is subject to change without notice. If you find any problems in the documentation, please report them to us in writing. This document is not warranted to be error-free. Except as may be expressly permitted in your license agreement for these Programs, no part of these Programs may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose. The platform-specific hardware and software requirements included in this document were current when this document was published. However, because new platforms and operating system software versions might be certified after this document is published, review the certification matrix on the My Oracle Support (formerly OracleMetaLink) Web site for the most up-to-date list of certified hardware platforms and operating system versions. The My Oracle Support (formerly OracleMetaLink) Web site is available at the following URL: or If the Programs are delivered to the United States Government or anyone licensing or using the Programs on behalf of the United States Government, the following notice is applicable: U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the Programs, including documentation and technical data, shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement, and, to the extent applicable, the additional rights set forth in FAR , Commercial Computer Software -- Restricted Rights (June 1987). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently dangerous applications. It shall be the licensee's responsibility to take all appropriate fail-safe, backup, redundancy and other measures to ensure the safe use of such applications if the Programs are used for such purposes, and we disclaim liability for any damages caused by such use of the Programs. 2

3 Copyright Oracle and Primavera are registered trademarks of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners. The Programs may provide links to Web sites and access to content, products, and services from third parties. Oracle is not responsible for the availability of, or any content provided on, third-party Web sites. You bear all risks associated with the use of such content. If you choose to purchase any products or services from a third party, the relationship is directly between you and the third party. Oracle is not responsible for: (a) the quality of third-party products or services; or (b) fulfilling any of the terms of the agreement with the third party, including delivery of products or services and warranty obligations related to purchased products or services. Oracle is not responsible for any loss or damage of any sort that you may incur from dealing with any third party. To view the list of third party component disclosures related to this product, see the Commercial Notices and Disclosures document for this product. 3

4

5 Contents Copyright... 2 Overview... 7 Purpose of this Document... 7 Conventions Used in this Document... 7 Before You Begin... 8 Setting Up HTTPS... 9 Creating a Certificate... 9 Configuring Contract Management to Use HTTPS Creating a Certificate Signing Request (CSR) Importing the Chained Certificate into the Keystore File Connecting to Contract Management Via HTTPS Warnings Users May Encounter Frequently Asked Questions

6

7 Overview Purpose of this Document This document describes the steps required to implement SSL/HTTPS on the Contract Management Web server. HTTPS uses the SSL protocol to encrypt the data traveling between the Web server and the client workstation. This encryption helps protect the data being transmitted. A Digital Certificate is used to confirm the identity of the server. Please review this entire document before proceeding. Note: This document is for Contract Management installations on JBoss only. WebLogic users should review the documentation from WebLogic for information about HTTPS implementation. Conventions Used in this Document This document uses the following conventions for items that may need to be modified: Convention Bold text Italic text Used to Indicate Bold text indicates items that you may need to modify to match the environment being used. Examples in this document will use the defaults created by a standard installation (for example, the drive and directory in which Contract Management is installed). Italic text shows values that you must either create or modify based on the organization (for example, the name of the company or a password). 7

8 Implementing HTTPS in Contract Management Before You Begin Note: For Contract Management using HTTPS, 12.x to 13.1 upgrades are a special case. If the prior version of Contract Management was using https, upgrading to Contract Management 13.1 will require the same modifications on the web server side as described in Configuring Contract Management to Use HTTPS (on page 11). Move the previously used keystore file to the appropriate new directory, and specify the correct keystore password in the server.xml file. For Standalone installs, the desktop shortcuts URL addresses for both Contract Management and Contract Management Administration must be modified. Ensure that both shortcuts point to an https address (as opposed to an http address), and are using the proper port number. Before beginning, prepare answers for the following questions. This information will be required. 1) Where is JBoss installed? The primary default location for all installs and upgrades is C:\jboss GA. Examples in this document will refer to the default location as JBOSS_HOME. 2) Where is the Java SDK installed? The default location is C:\jdk1.6.0_24. Examples in this document will refer to this as JAVA_HOME. 3) What is the DNS name clients use to connect? Example: myserver.mycompany.com This can usually be found by checking the address workstations use to connect to Contract Management. An Internet Service Provider can help establish an external domain name. 4) Will a Certificate Authority be used? A Certificate Authority acts as a Trusted Third Party to certify that the certificate can be trusted. Using a Certificate Authority allows the server to say "I trust this party to trust me" and the client to say "I trust this party to tell me I can trust this server." Most common Certificate Authorities are pre-authorized within Internet Explorer and other Web browsers. Use of a Certificate Authority is optional. Without it, the digital certificate on the Web server will be self-signed, and end users will be prompted to verify the identity of the server and accept the self-signed certificate. 5) When can the Contract Management Web server be taken off-line? The Contract Management Web server must be restarted for the changes to take effect. Prepare for a period of downtime in case problems are encountered. 6) What passphrase will be used for the certificate? This passphrase will only be used on the Web server. Client workstations will not need to know it. This is exclusively used when creating the certificate and configuring the Web Server. The sample passphrase secret is used in examples in this document. 8

9 Setting Up HTTPS Setting Up HTTPS The following tasks are all performed on the Contract Management Web server. Caution: To set up HTTPS: Only perform the following tasks if a Certificate Authority will be used: Creating a Certificate Signing Request (CSR) (on page 13) Importing the Chained Certificate into the Keystore File (on page 14) If you need to perform the preceding tasks, only proceed after testing the server with a self-signed certificate to verify that the following tasks completed properly: Creating a Certificate (on page 9) Configuring Contract Management to Use HTTPS (on page 11) 1) Creating a Certificate (on page 9) 2) Configuring Contract Management to Use HTTPS (on page 11) 3) Creating a Certificate Signing Request (CSR) (on page 13) 4) Importing the Chained Certificate into the Keystore File (on page 14) Related Topics Creating a Certificate... 9 Configuring Contract Management to Use HTTPS Creating a Certificate Signing Request (CSR) Importing the Chained Certificate into the Keystore File Creating a Certificate A digital certificate is needed to enable HTTPS. The Java SDK includes a utility called keytool which is used to create a Keystore file. Click Start and select Run or use a Command Prompt to run the following command: JAVA_HOME\bin\keytool -genkey -keyalg RSA -alias primavera -keystore JBOSS_HOME\server\<Your JBOSS domain for Contract Management>\conf\primavera.keystore -keypass your_passphrase -dname CN=your server s DNS name, OU=organizational unit, O=organization, L=city or locale, S=state or province, C=two-letter country abbreviation 9

10 Implementing HTTPS in Contract Management Notes: Oracle recommends that you run these commands from a Command Prompt to allow any error messages that appear to remain visible before the window is closed. Commands shown should be on one continuous line. Format restrictions of this document may prevent them from doing so. Where this document wraps a command to the next line, assume a space. After running this command, a prompt displays asking for the passphrase. This is the same passphrase as used in the command line, entered after -keypass (your_passphrase). In the preceding command: OU = Organizational Unit: the department or division within the company O = Organization: the name of the company L = City or Locale: where the server or the company is located S = State or Province: where the server or company is located C = Two-letter Country Abbreviation: where the server or company is located For Example: C:\jdk1.6.0_24\bin keytool -genkey -keyalg RSA -alias primavera -keystore C:\jboss GA\server\cm\conf\primavera.keystore -keypass secret -dname "CN=myserver.mycompany.com, OU=Customer Support, O=Oracle Primavera, L=Bala Cynwyd, S=Pennsylvania, C=US" Where cm is <Your JBoss domain for Contract Management>. The preceding example created a file called primavera.keystore in: C:\jboss GA\server\cm\conf\ It tells the certificate that the server s name is myserver.mycompany.com, the Organization Unit is Customer Support within the Organization Oracle Primavera in Bala Cynwyd in PA in US and created the certificate with the passphrase secret. Note: The server name must match that which the clients enter into the address bar when connecting to the Contract Management Web server. In the preceding example, this value is myserver.mycompany.com. If the client connects to there will be no problem. Connecting to or would prompt the user that the address to which they are connecting does not match the address entered in the certificate. This is only a warning. The end user can review the discrepancy, and decide whether to proceed. More detail is provided in the Connecting to Contract Management Via HTTPS (on page 15) section of this document. 10

11 Setting Up HTTPS Configuring Contract Management to Use HTTPS Once the digital certificate is created, Contract Management must be configured to use it and communicate via the HTTPS protocol. To make a backup file: 1) Stop the Contract Management Web server. 2) Find the file SERVER.XML located in: JBOSS_HOME\server\<Your JBOSS domain for Contract Management>\deploy\jbossweb.sar\ 3) Make a backup copy of this file before proceeding. You must store the backup in a directory that is completely outside of the entire JBoss directory. Failure to do so could prevent https from working. After you create a backup, open the original file in Notepad. If the file opens in Notepad and is not readable, close the file and open in WordPad. Edits to the file may be done in WordPad. However, you must save the file as Text Only. The SERVER.XML file contains information for both HTTP and HTTPS communication. By default, it uses the HTTP parameters, and the HTTPS section is commented out. The HTTP section must be commented out using the comment codes. To configure the SERVER.XML file: 1) Comment out the HTTP section. a. Type <!-- before the HTTP area you want to comment out. b. Type --> after the HTTP area you want to comment out. XML documents ignore the text located between the codes. For example, the following has only the first line commented out: <!-- A HTTP/1.1 Connector on port 80 --> <Connector protocol="http/1.1" port="80" maxthreads="250" strategy="ms" maxhttpheadersize="8192" emptysessionpath="true" enablelookups="false" compression="on" address="*" acceptcount="100" connectiontimeout="20000" redirectport="8443" disableuploadtimeout="true" URIEncoding="UTF-8" /> This changes to the following when the --> is moved to the end of the command, which comments out the entire command: <!-- A HTTP/1.1 Connector on port 80 <Connector protocol="http/1.1" port="80" maxthreads="250" strategy="ms" maxhttpheadersize="8192" emptysessionpath="true" enablelookups="false" compression="on" address="*" acceptcount="100" connectiontimeout="20000" redirectport="8443" disableuploadtimeout="true" URIEncoding="UTF-8"/> --> 2) Remove the <!-- and --> comments surrounding the HTTPS section, and change the following field values: port="8443" address="${jboss.bind.address}" keystorefile="${jboss.server.home.dir}/conf/chap8.keystore" keystorepass="rmi+ssl" 11

12 Implementing HTTPS in Contract Management For example: <!-- SSL/TLS Connector configuration using the admin devl guide keystore <Connector protocol="http/1.1" SSLEnabled="true" port="8443" address="${jboss.bind.address}" scheme="https" secure="true" clientauth="false" keystorefile="${jboss.server.home.dir}/conf/chap8.keystore" keystorepass="rmi+ssl" sslprotocol = "TLS" /> --> This changes to the following when the --> is moved from the end of the command to the end of the first line of the command, which comments out only the first line: <!-- SSL/TLS Connector configuration using the admin devl guide keystore --> <Connector protocol="http/1.1" SSLEnabled="true" port="443" address="*" scheme="https" secure="true" clientauth="false" keystorefile="c:\jboss ga\server\cm\conf\primavera.keystore" keystorepass="secret" sslprotocol = "TLS" /> In the preceding command: port="8443" changed to port="443" address="${jboss.bind.address}" changed to address="*" keystorefile="${jboss.server.home.dir}/conf/chap8.keystore" changed to keystorefile="c:\jboss ga\server\cm\conf\primavera.keystore" keystorepass="rmi+ssl" changed to keystorepass="secret" 3) Edit the following values: Port: The port number the Web server uses to communicate. The default is 443. Port= 443 keystorefile: The path to, and filename of, the primavera.keystore file. Use the following format: keystorefile= &{jboss.home.server.dir}\conf\primavera.keystore keystorepass: The passphrase used when creating the digital certificate (secret in the examples). keystorepass= secret 4) Save the SERVER.XML file. To configure the Primavera Administrator utility: 1) Open the Primavera Administrator utility directory. The default location for new Contract Management 13.1 installations is: <drive letter>:\program Files\Oracle\ContractManagement\utility\CMAdminConfig\ 2) Double-click the admincm.cmd file, provide the appropriate credentials depending on the database platform, and click OK. Default for Oracle: User Name: expadmin Password: expadmin Default for Microsoft SQL Server: User Name: exp Password: sql 3) Expand Contract Management 13.1 Settings\Web Server. a. Triple click the WebProtocol: parameter, and change it to https. 12

13 Setting Up HTTPS b. Triple click the WebPort: parameter and change it to ) Click the Save Changes button in the bottom right, and close the Primavera Administrator utility. 5) Start the Contract Management Web server. At this point, the Contract Management Web server will start with the self-signed certificate. Log in to Contract Management and verify the configuration of HTTPS at this point. Note: If the purpose of implementing HTTPS was solely to encrypt data sent across the network using the Secure Socket Layer, then no further steps are necessary. If HTTPS was implemented with the intention of reassuring end users that they are connecting to the correct server, then you may want to replace the self-signed certificate with one signed by a Certificate Authority. Creating a Certificate Signing Request (CSR) To create a Certificate Signing Request (CSR): 1) Stop the Contract Management Web server. 2) Run the following command to create a Certificate Signing Request to submit to the Certificate Authority: JAVA_HOME\bin\keytool -certreq -alias primavera -keystore JBOSS_HOME\ server\<your JBOSS domain for Contract Management>\conf\primavera.keystore -keypass your_passphrase -file primavera.csr For example: C:\jdk1.6.0_24\bin\keytool -certreq -alias primavera -keystore C:\jboss GA\server\cm\conf\primavera.keystore -keypass secret -file primavera.csr Where cm is <Your JBOSS domain for Contract Management>. Note: The utility will again prompt for the passphrase. 3) This will create a file called PRIMAVERA.CSR in the JAVA_HOME directory. Open this file in Notepad. Its contents will resemble the following: -----BEGIN NEW CERTIFICATE REQUEST----- MIIBvzCCASgCAQAwfzELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAlBBMRQwEgYDVQQHEwtCY WxhIEN5bnd5ZDEeMBwGA1UEChMVUHJpbWF2ZXJhIFN5c3RlbXMgSW5jMRkwFwYDVQQLExB DdXN0b21lciBTdXBwb3J0MRIwEAYDVQQDEwlsb2NhbGhvc3QwgZ8wDQYJKoZIhvcNAQEBBQ ADgY0AMIGJAoGBALETgrPDr5BamtGmdzb9SILUcUdjsJKYq38/Umw2KdEYJ76Z0hSGWuU4REbRG 3S1JfFNYwMUKC/HKA355Xp8kzw6zUICw9eMzRzAxkZLYR3WqPNfhiHhm4e6pTPaDpwOOYzoF0 8BHK0JiL7Y36NH/jtYG51ADVXOj6vBXK7DQ6ePAgMBAAGgADANBgkqhkiG9w0BAQQFAAOBg QBgmRSQYBBr6mH2eSB53GnZQX3j9SdyQvxsrSFmUzjhnjsnAOIYriJJoYY8TOh05iI9PuxBpDfVYl+T 1X6cGSRb2zBVkDWjc4BXJccADHawapb4mh0fj1OkfxQSFScE2f272PTrKFu8Ij6wjGn6tvr5pLASiutOa ZzIlrGyKXXrYw== -----END NEW CERTIFICATE REQUEST---- 4) Copy the entire contents of this file to submit to the Certificate Authority. The response received from the CA will look similar, but without the word REQUEST. 5) Save the contents of the response as a new Notepad document, and save it with the name PRIMAVERA.CER in the JAVA_HOME\bin directory. 13

14 Implementing HTTPS in Contract Management Notes: Make sure Notepad does not append.txt to the end of the file name. Also, ensure that there are no spaces at the end of, or following, the last line in the PRIMAVERA.CER file. This is the certificate created in the Creating a Certificate (on page 9) topic chained together with the CA s root certificate. Caution: Only perform the following tasks if a Certificate Authority will be used: Creating a Certificate Signing Request (CSR) (on page 13) Importing the Chained Certificate into the Keystore File (on page 14) If you need to perform the preceding tasks, only proceed after testing the server with a self-signed certificate to verify that the following tasks completed properly: Creating a Certificate (on page 9) Configuring Contract Management to Use HTTPS (on page 11) Importing the Chained Certificate into the Keystore File Some Certificate Authorities, including Verisign, may require an additional Intermediate Certificate to be imported prior to importing the Chained Certificate. Please review the CA s documentation before proceeding. More information on Verisign s Intermediate Certificate is covered in the Frequently Asked Questions (on page 16) section of this document. Caution: Only perform the following tasks if a Certificate Authority will be used: Creating a Certificate Signing Request (CSR) (on page 13) Importing the Chained Certificate into the Keystore File (on page 14) If you need to perform the preceding tasks, only proceed after testing the server with a self-signed certificate to verify that the following tasks completed properly: Creating a Certificate (on page 9) Configuring Contract Management to Use HTTPS (on page 11) To import the chained certificate into the Keystore file: 1) Run the following command to import the PRIMAVERA.CER: JAVA_HOME\bin\keytool -import -alias primavera -trustcacerts -file JAVA_HOME\bin\primavera.cer -keystore JBOSS_HOME\server\<Your JBOSS domain for Contract Management>\conf\primavera.keystore -keypass your_passphrase 14

15 Connecting to Contract Management Via HTTPS Example: C:\jdk1.6.0_24\bin\keytool -import -alias primavera -trustcacerts -file C:\jdk1.6.0_24\bin\primavera.cer -keystore C:\jboss GA\server\cm\conf\primavera.keystore -keypass secret Where: C:\jboss GA is the JBOSS_HOME cm is the <Your JBOSS domain for Contract Management> The digital certificate is now installed. 2) Start the Contract Management Web server. Connecting to Contract Management Via HTTPS Now that Contract Management has been modified to communicate via HTTPS, clients must change the URL to match. 1) Open the Web browser on the computer(s) that will connect to Contract Management. 2) Modify the shortcuts or bookmarks to match the new URL. Before: After: There is now an s attached to http in this example. Warnings Users May Encounter Different Browsers will display different messages and dialogs. The following are representative of what you will encounter. Note: The following sample warnings may change as software updates are delivered (for example, to Web browsers and Java). In IE7, if the digital certificate created was not signed by a Certificate Authority, or a Certificate Authority that the browser does not recognize, the following message displays: There is a problem with this website's security certificate. Click Continue to this website. At the login page for Contract Management, the Java Runtime Environment will prompt to accept its own security certificate. a. Click Install the Certificate. 15

16 Implementing HTTPS in Contract Management b. Select the Always trust content from this publisher option to permanently accept this certificate. c. Click Yes to accept this certificate for this session. If the address entered into the Address bar of the browser does not match the server name contained within the digital certificate, users will receive a warning similar to the following: Certificate Error If this message is due to a typo or error in the digital certificate, the primavera.keystore file on the web server can be deleted and recreated by returning to the Creating a Certificate (on page 9) topic. The browser is now connected to the Web server via a secure encrypted connection. Frequently Asked Questions Why implement HTTPS? HTTPS allows communication between the client browser and the Web server to be encrypted instead of sending in plain text. This makes it difficult for the communication to be intercepted and viewed by other parties. Does implementing HTTPS mean that all the communication is impenetrable and other security measures are unnecessary? No. As with any server, appropriate measures should be taken to safeguard the network, the computer, and the data. HTTPS is not a substitute for firewalls, safe password practices, and other security measures. Are there any down sides to HTTPS? Besides the time taken to implement, HTTPS does require a little more CPU usage on the server and the client. Additionally, the encrypted data tends to be larger than unencrypted data. As a result, there may be a small performance drop. How noticeable this is depends on the processing power of the Web server and the client computers, and the Internet or network connection between them. Most users do not experience a significant performance drop. Can HTTPS and HTTP be used at the same time? No. The Contract Management Web server can only support one protocol at a time. If HTTPS is implemented, all clients must now use it to connect. 16

17 Frequently Asked Questions If HTTPS is implemented with a self-signed certificate, can that certificate be signed later by a Certificate Authority? Yes. Simply follow the instructions described in the Creating a Certificate Signing Request (CSR) (on page 13) section of this document, and proceed from there. Remember to restart the Contract Management service. The primavera.keystore file was created incorrectly. Can this be fixed? Yes. Stop the Contract Management Web server and delete the existing primavera.keystore file. Follow the instructions in the Creating a Certificate (on page 9) section of this document to create a new one. Does port 443 have to be used? No. Any available port can be used for HTTPS communication. The URL that clients enter must now include :portnumber at the end of the server name. For example, if port 6557 is used, the URL must look like the following: Please remember that regardless of which port number is used, any firewalls or routers must be configured to allow HTTPS traffic on this port. Run the Primavera Administrator utility, or edit SERVER.XML to make this change. What needs to be done to revert to standard HTTP instead of HTTPS? Simply undo the changes made to the SERVER.XML and Administration utility files. If backup copies of these files were made before modifying, revert to those backups. The primavera.keystore file can be deleted, or just left there - it will not be used in any way while set to HTTP. How is Verisign s Intermediate CA Certificate installed? From Verisign.com find the Intermediate CA Certificate that corresponds to your certificate purchase. Copy and paste this into Notepad and save the file as intermediateca.cer in the JBOSS_HOME\bin folder. Be sure not to include any spaces or additional characters or lines at the end of the file. Modify the following as needed: JAVA_HOME\bin\keytool -import -alias intermediateca -keystore JBOSS_HOME\server\<Your JBOSS domain for Contract Management>\conf\primavera.keystore -trustcacerts -file JAVA_HOME\bin\intermediateCA.cer 17

18 Implementing HTTPS in Contract Management Example: C:\j2sdk1.6.0_14\bin\keytool -import -alias intermediateca -keystore C:\jboss GA\server\cm\conf\primavera.keystore -trustcacerts -file C:\j2sdk1.5.0_14\bin\intermediateCA.cer Where: C:\jboss GA is the JBOSS_HOME and cm is the <Your JBOSS domain for Contract Management> Further detail is available at the following location: Where can I find more information about HTTPS, SSL, and Certificate Authorities? The following websites can provide more detail: Is there a way to confirm the JAVA_HOME directory? Contract Management stores the path to the JAVA_HOME location within the exponline.properties file. The entry will resemble the following: Java_Home=C:\jdk1.6.0_24 When will the Certificate expire? By default, certificates will expire after 90 days. An expired certificate will not result in any loss of functionality. However, users will receive a warning message indicating the expiration. To change the expiration of the certificate, use the -validity parameter when creating the certificate. For information on creating the certificate, see the Creating a Certificate (on page 9) section of this document. Immediately following the parameter is a number representing days. JAVA_HOME\bin\keytool -genkey -keyalg RSA -alias primavera -validity XXX -keystore JBOSS_HOME\server\<Your JBOSS domain for Contract Management>\conf\primavera.keystore -keypass your_passphrase -dname CN=your server s DNS name, OU=organizational unit, O=organization, L=city or locale, S=state or province, C=two-letter country abbreviation For Example: C:\jdk1.6.0_24\bin\keytool -genkey -keyalg RSA -alias -validity 365 primavera -keystore C:\jboss GA\server\<Your JBOSS domain for Contract Management>\conf\primavera.keystore -keypass secret -dname CN=myserver.mycompany.com, OU=Customer Support, O=Primavera Systems, L=Bala Cynwyd, S=PA, C=US 18

19 Frequently Asked Questions Where: C:\jboss GA is the JBOSS_HOME. In the preceding example, -validity 365 sets the certificate to 365 days until expiration. This value may be changed to whatever number you require. How do I contact Customer Support? For instructions on how to submit a service request for technical support for your products, go to: This page provides the latest information for contacting support, and for information about the support renewals process. 19