How To Web Dispatcher and SSL
How To Web Dispatcher and SSL
How To Web Dispatcher and SSL
Copyright 2004 SAP AG. All rights reserved. No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. The information contained herein may be changed without prior notice. Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors. Microsoft, Windows, Outlook, and PowerPoint are registered trademarks of Microsoft Corporation. IBM, DB2, DB2 Universal Database, OS/2, Parallel Sysplex, MVS/ESA, AIX, S/390, AS/400, OS/390, OS/400, iSeries, pSeries, xSeries, zSeries, z/OS, AFP, Intelligent Miner, WebSphere, Netfinity, Tivoli, and Informix are trademarks or registered trademarks of IBM Corporation in the United States and/or other countries. Oracle is a registered trademark of Oracle Corporation. UNIX, X/Open, OSF/1, and Motif are registered trademarks of the Open Group. Citrix, ICA, Program Neighborhood, MetaFrame, WinFrame, VideoFrame, and MultiWin are trademarks or registered trademarks of Citrix Systems, Inc. HTML, XML, XHTML and W3C are trademarks or registered trademarks of W3C , World Wide Web Consortium, Massachusetts Institute of Technology. Java is a registered trademark of Sun Microsystems, Inc. JavaScript is a registered trademark of Sun Microsystems, Inc., used under license for technology invented and implemented by Netscape. MaxDB is a trademark of MySQL AB, Sweden. SAP, R/3, mySAP, mySAP.com, xApps, xApp, SAP NetWeaver, and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and in several other countries all over the world. All other product and service names mentioned are the trademarks of their respective companies. Data
contained in this document serves informational purposes only. National product specifications may vary. These materials are subject to change without notice. These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Group products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty. These materials are provided as is without a warranty of any kind, either express or implied, including but not limited to, the implied warranties of merchantability, fitness for a particular purpose, or non-infringement. SAP shall not be liable for damages of any kind including without limitation direct, special, indirect, or consequential damages that may result from the use of these materials. SAP does not warrant the accuracy or completeness of the information, text, graphics, links or other items contained within these materials. SAP has no control over the information that you may access through the use of hot links contained in these materials and does not endorse your use of third party web pages nor provide any warranty whatsoever relating to third party web pages. SAP NetWeaver How-to Guides are intended to simplify the product implementation. While specific product features and procedures typically are explained in a practical business context, it is not implied that those features and procedures are the only approach in solving a specific business problem using SAP NetWeaver. Should you wish to receive additional information, clarification or support, please refer to SAP Consulting. Any software coding and/or code lines / strings (Code) included in this documentation are only examples and are not intended to be used in a productive system environment. The Code is only intended better explain and visualize the syntax and phrasing rules of certain coding. SAP does not warrant the correctness and completeness of the Code given herein, and SAP shall not be liable for errors or damages caused by the usage of the Code, except if such damages were caused by SAP intentionally or grossly negligent.
1 Scenario
This How to guide describes how the SAP Web Dispatcher can be configured if SSL is involved in some way. The general setup throughout this document is that a web browser calls a web page on the SAP Web AS Java 6.40, but instead of calling the SAP Web AS directly the SAP Web Dispatcher is called. The SAP Web Dispatcher forwards this request to the SAP Web Application Server (Web AS).
The requirement to use the SAP Web Dispatcher might be due to performance reasons (load balancing) or security reasons (reverse proxy). The SAP Web Dispatcher can act as a reverse proxy for SAP systems, but has not all the features a full blown reverse proxy has. All demos and examples within this document make use of the SAP Web AS 6.40 Java; nevertheless most of it is valid for the SAP Web AS 6.40 ABAP as well. See appendix for a link to help.sap.com. To illustrate configuration steps the used operating system in this how to paper is Linux, but with the knowledge of another operating system the reader should be able to transfer the OS specific steps into any other supported operating system. It will be assumed that the reader is familiar with SSL and the usage of certificates. For some background information on SSL and encryption it is recommended to check the links in the appendix. It is recommended to read all the introduction and common chapters of this how to paper regardless which SSL scenario will be implemented (until and including section 3.3). After section 3.3 it is only necessary to read the chapter specific to the chosen scenario.
2 Introduction
This document discusses three different scenarios: SSL termination, SSL re-encryption and End-to-End SSL. There is no general recommendation which scenario should be implemented since each of them has advantages and disadvantages. One important criterion for the decision which scenario to use is the security guidelines and policies valid within the organization.
-1-
A scenario like this should only be considered if the network between the SAP Web Dispatcher and the SAP Web AS is secure. Furthermore the advantages of this setup are that a network IDS (intrusion detection system) can be used, the SSL decryption load is shifted away from the Web AS (SSL offloading) and last but not least the SAP Web Dispatcher can check for client certificates to allow access into the internal network.
Using this setup the SAP Web Dispatcher can interpret session cookies for load balancing. The downside of this scenario is that SSL termination and (re-)encryption is a CPU intensive task.
The difference compared to SSL re-encryption is that the SAP Web Dispatcher cant look into the browsers request when using End-to-End SSL. This means that the SAP Web Dispatcher cannot interpret
-2-
session cookies (as they are SSL encrypted as well). Routing to the different application servers of the SAP Web AS can now only be done based on the browsers IP address. More details can be found in section 3.6.
Figure 3.1.1 As shown in figure 3.1.1 we use the directory /webdisp for the SAP Web Dispatcher and the directory /secudir to store the SAP crypto lib. In our example the user who will run the SAP Web Dispatcher is i028931. The next step will be to download the necessary software. The SAP crypto lib is bound to German export regulations and may be subjected to import regulations for your country. The SAP cyrpto lib can only be downloaded with a customer specific S-user from SAPs service market place (http://service.sap.com). Copy these crypto lib files into the /secudir. Copy the file ticket as well into the sub directory sec. These steps are shown in figure 3.1.2.
Figure 3.1.2
-3-
Download the latest SAP Kernel Release 6.40 from SAPs service market place for your operating system. http://service.sap.com/download SAP Support Packages SAP Support Packages and Patches Entry by Application Group SAP Netweaver SAP Netweaver SAP Netweaver 04 Entry by Component Application Server ABAP SAP Kernel 6.40 32-bit Linux on IA32 32bit #Database independent SAPEXE_ <Patch-Level>.SAR. From the same directory download SAPCAR. Copy both files into the /webdisp directory. Use ./SAPCAR xvf SAPEXE_<Patch-Level>.SAR in order to extract the file. If SAPCAR cant be executed, then check note 522119. Most of the extracted files can be deleted, keep at least the following:
Figure 3.1.3 Extract the File icmadmin.SAR with ./SAPCAR xvf icmadmin.SAR. All software needed is in place now. During the bootstrapping process the SAP Web Dispatcher creates an initial profile and starts automatically. Please follow the steps shown in figure 3.1.4.
Figure 3.1.4 Since the configuration is not complete yet, the web dispatcher process has to be stopped with the command:
-4-
kill -2 <PID>. To start the SAP Web Dispatcher type in the command sapwebdisp pf=sapwebdisp.pfl During the bootstrapping it is necessary to specify the Message Server host and port of the SAP Web AS. For performance reasons it is recommended to use the IP address (to save a DNS lookup). Furthermore an Instance Number for the SAP Web Dispatcher (Range from 00 to 98), which has to be unique in case multiple SAP Web Dispatchers are running on the same host, has to be specified. Last but not least it is necessary to specify a port number for the SAP Web Dispatcher, in this example we have chosen 60000. If the port should be either the default http port 80 or the default https port 443 please follow the guidelines in note 421359 in case you run the SAP Web Dispatcher on a UNIX system. The bootstrapping process created two files the first file is icmauth.txt and contains the hashed password of the icmadm user which is used for administration of the SAP Web Dispatcher via http://<web dispatcher server>:<port>/sap/wdisp/admin, here http://sgpss059vm07.sin.sap.corp:6000/sap/wdisp/admin. The password in clear text is given on the console and can be changed later. The second file is the profile sapwebdisp.pfl. Open this profile with a text editor and add the parameter wdisp/shm_attach_mode = 6 This parameter will reuse already existing shared memory segments, or if they dont exist create them. The profile created so far is good for plain http communication. This profile will be extended during the next chapters to configure the different SSL scenarios.
Figure 3.2.1 Be careful the variable LD_LIBRARY_PATH might already be set, dont overwrite them! In order to terminate the SSL connection at the SAP Web Dispatcher we need to create a certificate and a SSL key pair (PSE - Personal Security Environment). To create a SSL key pair and a certificate request enter the command shown in figure 3.2.2. Be careful how to choose the CN, as the CN you should choose the server name which decrypts the SSL, this can be the SAP Web Dispatcher (in case of SSL termination or reencryption) or the Web AS (in case of End-to-End SSL). In the latter case see section 3.6.
-5-
get_pse -p -x
-r
SSL key pair will be created PSE file where the keys are stored PIN to protect the keys (choose a password and enter it in clear text). If this parameter is not used sapgenpse will ask for a PIN interactively. This gives some extra security since nobody can read the password from the screen or can find it in command history. File where the certificate request is stored as well as the common name of the owner
The file SAPSSL.req is a simple ASCII file which content has to be sent to a CA (Certification Authority). According to the rules of the CA, the CA will sign that request and return a file with the signed certificate. SAP offers CA services via http://service.sap.com/Trust. On that page it is possible to sign test certificates instantly. The signed certificate has to be imported into the PSE, copy it to the SAP Web Dispatcher server and execute the following command:
Figure 3.2.3 The following options are used: import_own_cert Import the certificate generated from the CA -c certificate file (the response from the CA) -p PSE file where the keys are stored -x PIN to protect the keys (the password chosen above). If this parameter is not used sapgenpse will ask for a PIN interactively. This gives some extra security since nobody can read the password from the screen or can find it in command history. If this command fails, it might be necessary to import the certificate chain with the switch r. The PSE is complete now, remember that the PSE is password protected. That means that the SAP Web Dispatcher cant access the PSE file without the password. Instead of supplying the password in the profile it is necessary to create a credential file. The owner of this file has access to the PSE. To create the credential file enter:
Figure 3.2.4 The following options are used: seclogin Create the credentials file -p PSE file where the keys are stored -x PIN to protect the keys (the password chosen in figure 3.2.4). If this parameter is not used sapgenpse will ask for a PIN interactively. This gives some extra security since nobody can read the password from the screen or can find it in command history. -O User who should have access to the credential file
-6-
This command has created a file cred_v2. Since this file contains the password for the SAP Web Dispatcher user its access should be limited to the owner. See figure 3.2.5.
Figure 3.2.5 Now it is necessary to specify inside the sapwebdisp.pfl profile where the SAP Web Dispatcher can find the SAP crypto lib and the PSE. Add the following parameters to the sapwebdisp.pfl file: DIR_INSTANCE =/secudir ssl/ssl_lib =/secudir/libsapcrypto.so ssl/server_pse =/secudir/SAPSSL.pse The result is a SAP Web Dispatcher file with the common SSL parameters. This profile so far is not complete and will not work. It will be completed during the next sections.
-7-
ms/server_port_1 = PROT=HTTP, PORT=0 The zero specifies, that the SAP Web Dispatcher can open outgoing connections via http (to the messages server of the Web AS), but cant receive incoming requests via http. HTTPS is possible for outgoing and incoming requests. The SAP Web Dispatcher needs to be able to connect to the https port of the SAP Web AS Message Server. To achieve this change the SAP Web Dispatcher parameter ms/http_port to ms/https_port ms/https_port = 8101 The port specified here has to be the same one as specified above for the Web AS. Add the parameter wdisp/server_info_protocol = https to specify that the Web AS server information is transferred via https. So far the common configuration for the SSL metadata exchange is done. The only parameter missing to complete the SSL metadata exchange is icm/server_port_<No>. The value of this parameter depends on the scenario you want to configure. It specifies how the SAP Web Dispatcher connects to the message server of the Web AS. If you just want to startup the SAP Web Dispatcher to see if it can connect correctly, then add temporarily the parameter icm/server_port_1 = PROT=HTTPS, PORT=0 This parameter allows outgoing https connections, but no incoming ones since the port for incoming connections is set to zero.
-8-
wdisp/add_client_protocol_header = true Since the setup in this How to guide doesnt require the client to present an own certificate, add the parameter icm/HTTPS/verify_client = 0 to prevent the SAP Web Dispatcher from asking for a client certificate. If the security guidelines of the organization enforces the use of client certificates set this parameter to one. Restart the SAP Web Dispatcher and connect via https://sgpss059vm07.sin.sap.corp:60000.
-9-
browser. To avoid this warning use a certificate issued on the name of the SAP Web Dispatcher for the SAP Web AS. For end-to-end SSL the SAP Web Dispatcher only forwards the request to the SAP Web AS. Set the following SAP Web Dispatcher parameter for the routing of incoming requests: icm/server_port_0 = PROT=ROUTER,PORT=60000 In order to establish an https connection between the SAP Web Dispatcher and the SAP Web AS for the exchange of the SSL metadata add the parameter: icm/server_port_1 = PROT=HTTPS,PORT=0 These are all parameters which have to be specified for the end-to-end SSL setup. Since the SAP Web Dispatcher cant look into the requests (including all cookies) the load balancing has to be done via the IP address. If users access the internet via a proxy, the SAP Web Dispatcher sees for these users only the proxys IP address. Since the ISPs can route the request through different proxies during one session the IP address of the user may change. This would lead to the problem that during a state full session the users request may get routed to different application servers where no session information are available. To overcome this problem of a changing IP address set the parameter wdisp/HTTPS/sticky_mask The value of this parameter (which is an IP address) will be combined with the incoming IP address of the client or proxy. The result will be used as the clients IP address, this way the SAP Web Dispatcher doesnt distinguish among the lowest bits of the IP address and all requests of one user get routed to the same application server during the session.
4 Appendix
Example SAP Web Dispatcher profile for SSL Termination (with SSL metadata exchange): SAPSYSTEM = 1 wdisp/auto_refresh = 120 wdisp/max_servers = 100 wdisp/shm_attach_mode = 6 rdisp/mshost = sgpss059vm01.sin.sap.corp ms/https_port = 8101 DIR_INSTANCE=/secudir ssl/ssl_lib=/secudir/libsapcrypto.so ssl/server_pse=/secudir/SAPSSL.pse icm/server_port_0 = PROT=HTTPS,PORT=60000 icm/HTTP/admin_0 = PREFIX=/sap/wdisp/admin,DOCROOT=./admin wdisp/server_info_protocol = https wdisp/ssl_encrypt = 0 wdisp/add_client_protocol_header = true icm/HTTPS/verify_client = 0
Example SAP Web Dispatcher profile for SSL Termination (without SSL metadata exchange): SAPSYSTEM = 1 wdisp/shm_attach_mode = 6 rdisp/mshost = sgpss059vm01.sin.sap.corp
- 10 -
ms/http_port = 8101 DIR_INSTANCE=/secudir ssl/ssl_lib=/secudir/libsapcrypto.so ssl/server_pse=/secudir/SAPSSL.pse wdisp/auto_refresh = 120 wdisp/max_servers = 100 icm/server_port_0 = PROT=HTTPS,PORT=60000 icm/server_port_1 = PROT=HTTP,PORT=0 icm/HTTP/admin_0 = PREFIX=/sap/wdisp/admin,DOCROOT=./admin wdisp/ssl_encrypt = 0 wdisp/add_client_protocol_header = true icm/HTTPS/verify_client = 0 Example SAP Web Dispatcher profile for SSL Re-encryption (with SSL metadata exchange): SAPSYSTEM = 1 wdisp/shm_attach_mode = 6 rdisp/mshost = sgpss059vm01.sin.sap.corp ms/https_port = 8101 DIR_INSTANCE=/secudir ssl/ssl_lib=/secudir/libsapcrypto.so ssl/server_pse=/secudir/SAPSSL.pse wdisp/auto_refresh = 120 wdisp/max_servers = 100 icm/server_port_0 = PROT=HTTPS,PORT=60000 icm/HTTP/admin_0 = PREFIX=/sap/wdisp/admin,DOCROOT=./admin wdisp/server_info_protocol = https wdisp/ssl_encrypt = 2 icm/HTTPS/verify_client = 0 wdisp/ssl_certhost = sgpss059vm01.sin.sap.corp Example Profile for end-to-end SSL (with SSL metadata exchange): SAPSYSTEM = 1 wdisp/shm_attach_mode = 6 rdisp/mshost = sgpss059vm01.sin.sap.corp ms/https_port = 8101 DIR_INSTANCE=/secudir ssl/ssl_lib=/secudir/libsapcrypto.so ssl/server_pse=/secudir/SAPSSL.pse wdisp/auto_refresh = 120 wdisp/max_servers = 100 icm/server_port_0 = PROT=ROUTER,PORT=60000 icm/server_port_1 = PROT=HTTPS,PORT=0 icm/HTTP/admin_0 = PREFIX=/sap/wdisp/admin,DOCROOT=./admin wdisp/server_info_protocol = https Further information the SAP Web Dispatcher can be found at: Know How Call SAP Web Dispatcher: http://sdn.sap.com Events SDN Webinar Schedule 09 Dec 2004 SAP Notes: 538405, 552286 Parameters for SAP Web Dispatcher configuration for Java and ABAP backend systems http://help.sap.com/nw04 English SAP NetWeaver Solution Life Cycle Management
- 11 -
System Management SAP Web Dispatcher The SAP Web Dispatcher Profile Parameters Further information on SSL can be found at:
RFC 2246 on TLSv1 (found on http://www.rfc-editor.org) http://www.w3c.org http://www.openssl.org Configuring the Use of SSL on the SAP J2EE Engine - http://help.sap.com/nw04 English SAP NetWeaver Security Network and Transport Layer Security Configuring the Use of SSL on the SAP J2EE Engine
- 12 -
www.sap.com/netweaver