Ssl

Enabling SSL for the SAPJ2EE engine

1/43

Installation guide:

Enabling SSL for the SAPJ2EE Engine


2/43

1. Overview ...........................................................................................................................4

Workflow Overview ............................................................................................. 4

2. Downloading the required cryptographic software ...........................................................5

3. Configuring the SAP J2EE Engine for secure communication.........................................6

Enabling SSL functionality .................................................................................. 6

Installing the IAIK crypto library installation................................................. 6

Enabling the keystore and ssl services....................................................... 7

Configuring key pairs and certificates ................................................................. 7

Creating a key pair and a self-signed certificate ......................................... 8

Creating a certificate signing request (for CA signing) .............................. 10

Loading a CA-signed certificate chain ...................................................... 12

Configuring the ssl service................................................................................ 13

Verifying secure communication ....................................................................... 13

4. Integration of external web servers .................................................................................18

IIS ISAPI plugin installation............................................................................... 18

Uninstall In-Q-My ISAPI modules ............................................................. 18

ISAPI module installation.......................................................................... 24

Finishing the installation............................................................................ 30

INI file settings .......................................................................................... 30

Enabling SSL redirection with the ISAPI module ...................................... 31

Requirements ................................................................................................... 31

Important considerations................................................................................... 32

SAP SSL installation......................................................................................... 32

Apache web server ........................................................................................... 35


3/43

5. Appendix A : How to sign a server certificate with Microsoft Certification Authority..36


4/43

1. Overview

This document provides detailed instructions for configuring the SAP J2EE Engine 6.20 for secure communication.

This chapter includes:

A description of the related software components

An overview of the configuration workflow

A list of additional documentation

Workflow Overview

Getting the SAP J2EE Engine ready for secure communication requires more than copying a few files. The following is a list of steps required to achieve this. This guide will take you through all the steps listed below, and will refer you to supplemental documentation when needed.

1. Decide on your system configuration: Are you just configuring the SAP J2EE Engine for secure communication or do you use the J2EE Engine in combination with another Web Server?

2. Download the required cryptographic software.

3. Configure the SAP J2EE Engine for secure communication.

4. Integrate the SAP J2EE Engine with another Web Server.


5/43

2. Downloading the required cryptographic software

Due to export restrictions on military and dual use goods, the cryptographic modules required for secure communication are not part of the SAP J2EE Engine installation package. You have to download them separately from the SAP Service Marketplace.

To download the cryptographic software:

1. Start your browser and browse to http://service.sap.com/swcenter.

2. Log in with your SAP s-user Id.

3. Navigate to SAP Cryptographic Software.

4. Sign the agreement on export regulations (if this is your first visit to the site).

5. Select the Java Cryptographic Toolkit and download it to a temporary directory on your system.

6. Select the SAP Cryptographic Library and download it to a temporary directory on your system (only for integration with Microsoft Internet Information Server).


6/43

3. Configuring the SAP J2EE Engine for secure communication

Enabling SSL functionality

Installing the IAIK crypto library installation

To unpack the cryptographic software:

1. Obtain the SAPCAR.exe tool (see SAP Note 212 876).

2. Create a directory named CryptoToolkit in the temporary directory mentioned above.

3. Open a command window in the CryptoToolkit directory.

4. Unpack the Java Cryptographic Toolkit:

SAPCAR xvf ..\SAPJAVACRYPTOTOOLKIT.CAR

This creates the files LEGAL.TXT, README.TXT, iaik_jce.jar, iaik_jsse.jar, iaik_ssl.jar. and w3c_http.jar.

To install the cryptographic software:

1. Copy the Java archive files iaik_jce.jar, iaik_jsse.jar and iaik_ssl.jar to the following directories:

For the standalone SAP J2EE Engine:

\admin\lib \alone\additional-lib

For a cluster installation of the SAP J2EE Engine

\admin\lib \cluster\dispatcher\additional-lib \cluster\server\additional-lib

2. Copy the Java archive file w3c_http.jar to the following directory:

For the standalone SAP J2EE Engine:

\alone\additional-lib


7/43

For a cluster installation of the SAP J2EE Engine

\cluster\server\additional-lib

Enabling the keystore and ssl services

After installing the IAIK libraries, you have to make sure that the SSL and the keystore service are started automatically during the start-up of the SAPJ2EE engine.

To enable the keystore and ssl services:

1. Shut down all running instances of the SAPJ2EE engine server (service) and the dispatcher.

2. Launch the SAP J2EE Engine Config tool by choosing:

Start Programs SAP J2EE Engine 6.20 Tools Config tool

3. Change the Startup Mode of the keystore service from Manual to Always:

For the standalone SAP J2EE Engine, navigate to alone services keystore and choose Always from the Startup Mode dropdown list..

For a cluster installation of the SAP J2EE Engine, change the Startup Mode in both the cluster/dispatcher services keystore and cluster/server services keystore service nodes.

4. Navigate to the ssl service(s) and set the Startup Mode from Manual to Always, too.

5. From the File menu, click Apply to save your changes.

6. Close the SAP J2EE Engine Config tool.

7. Start the SAP J2EE Engine.

Configuring key pairs and certificates

The SAP J2EE Engine comes with some pre-configured test certificates: a self-signed root certificate, and a chained test certificate. Using these certificates, it is possible to check that the basic SSL functionality is working.

For productive use, these certificates are not useful to create a trust relationship.


8/43

Creating a key pair and a self-signed certificate

Even if you want to have your certificates signed by an external CA, you have to generate your own self-signed certificate first.

To create a key pair and a self-signed certificate:

1. Launch the SAP J2EE Engine Administrator by choosing:

Start Programs SAP J2EE Engine 6.20 Administrator

2. Connect to the running J2EE Engine by choosing:

Connect Login

3. Enter the appropriate values into the UserName:, Password:, Host: and Port: fields and click OK.

4. In the left pane, navigate to Cluster Server One Services keystore.

You should see the following screen:


9/43

5. Change to the Certificate Generation tab.

6. Edit the Subject Properties: change the record values to match your requirements. Use the TAB key to change between input fields.

Change the Common Name to the fully qualified host name that you want to use in communication with the J2EE Engine.

After changing the Common Name value, submit your editing with the TAB key.

7. Choose a name for the certificate and enter it in the Key Alias field.

8. Click the Generate button.

Based on your editing, the SAP J2EE Engine Administrator generates a new key record containing the self-signed certificate. It stores the key record in the keystore of the SAP J2EE Engine.


10/43

Result

You have created a self-signed certificate in your keystore.

You can now configure the ssl service to use this certificate for testing.

If you do not plan to have the certificate signed by a Certificate Authority, skip to Configuring the ssl service on page 13.

Creating a certificate signing request (for CA signing)

This procedure only applies if you want to have your certificate signed by a Certificate Authority (CA).

To create a certificate signing request:

1. Activate the Keystore admin tab.


11/43

2. Select the newly generated certificate and click Store.

3. In the pop-up window, enter a filename and choose PKCS#8 Private Key (*.p8) from the Files of Type list. Click OK to save the private key.

Always enter file names with the appropriate extension the J2EE Engine Administrator does not add a default extension.

The default directory for storing and loading certificates and keys is the /admin directory.

After saving the private key file, you are asked to store the certificate. Click Cancel to skip saving the certificate itself.

4. Click Generate CSR to create the Certificate Signing Request.

5. In the pop-up window, enter a filename and choose PKCS#8 Private Key (*.p8) from the Files of Type list. Click OK to save the private key.


12/43

Result

The certificate signing request file is stored on your disk.

Send the certificate request file to a trusted certificate authority, e.g. Verisign. The certificate authority will sign the certificate and return the signed server certificate.

Refer to Appendix A for additional information about the Microsoft CA on Windows 2000 Advanced Server.

Loading a CA-signed certificate chain

This procedure only applies if you have your certificate signed by a CA.

To load a signed certificate into the J2EE Engine keystore:

1. Start the J2EE Engine Administrator, log on to the SAP J2EE Engine and navigate to the keystore service.

Check that you have generated a private key file from your self-signed certificate before proceeding.

2. Select the self-signed certificate from which you have generated the Certificate Signing Request and click Delete.

You cannot load a certificate into an existing keystore entry Therefore you have to delete the self-signed certificate before loading the CA-signed one.

3. Click the Load button.

4. In the pop-up box, choose PKCS#8 Private Key (*.p8) from the Files of Type list and select the private key file youve generated when creating the CSR file. Click OK.

The pop-up box changes and asks for the first certificate of a certificate chain.

5. Select the signed certificate file youve received from the Certificate Authority and click OK.

If your certificate file does not show up in the file list, choose All Files (*.*) from the Files of Type list.


13/43

6. Click Cancel to stop loading additional certificate chain elements.

The signed certificate appears in the Keystore entries list.

7. Verify the contents of your server certificate.

Select the imported certificate in the Keystore entries list. Scroll the Info pane and check whether the data in the Chain info section is correct.

Result

You have loaded the signed certificate in your keystore.

You can now configure the ssl service to use this certificate.

Configuring the ssl service

In the ssl service, you have to assign a certificate for new and active sockets.

To configure the ssl service:

1. Navigate to Cluster Server One Services ssl.

2. Choose Dispatcher One and activate the Certificates tab in the lower right pane.

3. Assign your server certificate to new and active sockets as follows:

Choose New Sockets in the Configuration pane.

Choose Add in the Certificates tab and select your server certificate from the pop-up list. Close the pop-up list with OK.

Choose Active Sockets in the Configuration pane.

Add your server certificate to each socket in the socket list.

4. Close the SAP J2EE Engine Administrator.

Verifying secure communication

Connect with https://mymachinename:myPort/.

To verify if the certificate is installed properly you can select View certificate button from the following Internet Explorer dialog box, when you connect to the web site for the first time.


14/43

As a result you should see the same signed and generated certificate that we imported into the servers keystore.


15/43


16/43

Tip : If you want this dialog to disappear in the future you have to double click the root certificate in the certificate chain and press the Install Certificate button and follow the Internet Explorer Certificate Import Wizard till the end.


17/43

After the import you can open your Internet Explorer browser and select Tools Options from the menu bar. Then select the Content tab and press the Certificates button.

Select the Trusted Root Certification Authorities tab and verify if the browser trusts our CA certificate that we recently imported into the browser store.

Caution:

The SSL browser warning will pop up all the time if the Common Name (CN) of the certificate does not match the URL machine name in the browser, e.g. the browser wants to connect to https://myhost/dummy.html but the CN of the SAPJ2EE server certificate is localhost (CN=localhost). Then the browser will prompt the warning dialog again.


18/43

4. Integration of external web servers

The following chapter describes how to integrate the SAPJ2EE engine into a landscape with other external web servers.

IIS ISAPI plugin installation

For Win32 operating system installations the desired web server is the IIS web server from Microsoft. To allow a smooth and easy integration into the IIS web server you need to install the SAPJ2EE engine ISAPI module plugin. The plugin allows certain requests to be redirected to the SAPJ2EE engine. The redirection also works for HTTPS scenarios. This section describes the installation procedure for the SAPJ2EE IIS ISAPI filter and extension module. To use the ISAPI module the user has to follow the installation procedures, described in the upcoming sections.

Uninstall In-Q-My ISAPI modules

Before we start with the installation of the new ISAPI modules we have to uninstall the previous versions of the InQMy- or J2EE-PlugIn (ISAPI modules). You can skip this section if you have no previous versions installed on your computer.

Select Properties from the popup menu after a right click on the top level node of the IIS snap-in.


19/43


20/43

Press the Edit button to change the global configuration of the IIS server.


21/43

Select the ISAPI Filters tab and select the In-Q-My (or SAPJ2EE) filter item and press the Remove button.


22/43

Select the scripts node inside the IIS snap-in an after right click on the node select Properties from the popup menu.


23/43

Press the Configuration button in the Virtual Directory tab to remove the extension form the list of extensions in the IIS script directory.

Select the ISAPI extension (either the InQMyProxyExt.dll or the SAPJ2EE.dll) in the App Mappings tab and press the Remove button

Note: If you want to uninstall a previous version of the SAPJ2EE.dll you are also allowed just to rename the old SAPJ2EE.dll and copy the new version of the DLL and the INI file to the Inetpub\Scripts directory. After that you have to restart your IIS server to apply the changes.


24/43

ISAPI module installation

Copy the SAPJ2EE.DLL and the SAPJ2EE.INI file from the directory \tools\lib\IIS_module\isapi into the Scripts directory of the IIS (e.g. C:\Inetpub\Scripts). Then open the MMC IIS snap-in. Select Properties from the popup menu after a right click on the top level node of the IIS snap-in.


25/43

Press the Edit button to change the global configuration of the IIS server.


26/43

Click on the ISAPI Filters tab and add the SAPJ2EE ISAPI filter to the list of filters by pressing the Add button. Then select the SAPJ2EE.DLL file on your hard drive and choose any name for the filter with a high priority.

After setting up the filter we have to set up the ISAPI extension inside the Scripts application of the IIS.


27/43

Select the scripts node inside the IIS snap-in an after right click on the node select Properties from the popup menu.


28/43

Create the Scripts application by pressing the Create button.


29/43

After that press the Configuration button to add the extension to the list of extensions for the IIS.

In the dialog Application Configuration click the Add button to add the extension. Then select the SAPJ2EE.DLL file which you have copied before as the executable and choose * as extension.


30/43

Finishing the installation

Open the SAPJ2EE.INI file in the scripts directory of the IIS and change the settings of the parameters extension.url and url.mapping for your application. Restart the IIS after the complete installation process is finished.

For further information on bug fixes and changes have a look at the Readme.txt file in the filter installation package.

INI file settings

The following section will describe the most important settings of the SAPJ2EE INI file in detail.

extension.url

The parameter extension.url allows you to redirect all requests for the ISAPI module extension to any desired relative path from the IIS root directory. e.g. :

extension.url = /scripts/SAPJ2EE.dll

All requests that the SAPJ2EE ISAPI filter redirects to the SAPJ2EE ISAPI extension are send to /scripts/SAPJ2EE.dll. Thats the default location of the ISAPI module.

url.mapping

This is the most important parameter in the INI file. It specifies the redirection rules for the ISAPI filter. The request from the browser is first send to the IIS. The IIS subsequently calls all installed ISAPI filter to process the request. If the request matches one redirect rule specified in the url.mapping parameter the SAPJ2EE ISAPI filter redirects the request to the SAPJ2EE ISAPI extension.

e.g. :

http: /test --> http://myServer:8100

The incoming http request to a path /test is forwarded to the SAPJ2EE engine using this URL: http://myServer:8443/test

https: /test --> https://myServer:8443

The incoming https request to a path /test is forwarded to the SAPJ2EE engine using this URL: https://myServer:8443/test


31/43

https: /test --> http://myServer:8100

The incoming https request to a path /test is forwarded to the SAPJ2EE engine using this URL: http://myServer:8100/test

If you want to specify more than one mapping you have to separate the mappings using different lines and a \ escape sequence.

http: /abc --> http://localhost:8100 \ https: /abc --> https://localhost:8443 \ http: /test --> http://localhost:8100

The last line of the enumeration is not allowed to use the \ escape sequence.

General format of the URL mapping parameter. [protocol:] [relative path] --> [URL] (\)

log.level

This flag controls the logging level of the filter and the extension. Log level 1 is the lowest logging level, whereas log level 3 nearly loggs all the activities.

1 : logs the start-up phase of the ISAPI module and the INI filconfiguration.

2 : logs basic HTTP traffic information such as request and response and all I internal error messages

3 : additionally the complete HTTP data is written into a extra log

The rest of the parameters are described in detail in the SAPJ2EE INI file.

Enabling SSL redirection with the ISAPI module

This section describes the installation procedure for enabling SSL redirection support using the SAPCRYPTOLIB SSL implementation.

Requirements

The SSL support requires the current release of the SAPCRYPTOLIB on the target system.

The delivery of the SAP Cryptographic Library underlies German export regulations and is not available to all customers. If you are authorized to


32/43

download the library, you will automatically have the "SAP Cryptographic Library" structure offered when you access the download site. Contact your local subsidiary if you cannot access the library.

You must also adhere to any import regulations that may apply.

The SAP Cryptographic Library is available for download from the SAP Service Marketplace at http://service.sap.com/crypto. You need to have a valid S-User account that is allowed to download restricted and cryptographic software.

The upcoming chapters assume that you already installed a valid server certificate for the SAPJ2EE engine as described in the previous chapters.

Important considerations

To establish a SSL connection between the ISAPI module and the SAPJ2EE engine it is necessary to that the common name (CN) of the SAPJ2EE server certificate should match the host name that you choose in the ISAPI filter INI file as redirection address, otherwise the SAP SSL API will not connect properly.

E.g. : The content of the SAPJ2EE INI file looks like this:

url.mapping = https: /abc --> https://myhost.test.com:8443 \

The SSL connection between the ISAPI module and the SAPJ2EE server can only be established if the common name ( CN ) of the previously created and installed server certificate is myhost.test.com.

SAP SSL installation

The SAP SSL installation consists of 3 files ( sapgenpse.exe ,sapcrypto.dll and ticket). The following steps describe how to set up the SAP SSL library to run properly.

Create a folder C:\sec. (You can also choose any other folder location or name.)

Copy the files SAPGENPSE.exe, ticket and sapcrypto.dll into this directory.

Copy the sapcrypto.dll into the WinNT\System32 folder.


33/43

Create a system environment variable SECUDIR = c:\sec as shown in the next picture and add this directory to your system path environment.

Reboot your machine after adding the environment variable to your system variables.

Export the generated SAPJ2EE test server certificate into a certificate file and store it somewhere on your hard disk. To export a server certificate from the SAPJ2EE engine you have to follow these steps:

o Open the SAPJ2EE Administrator application and login.

o Select the generated test certificate from the key store and click the Store button. Choose the Base64 encoded file type and choose any name and location for the certificate export files. Since SAPJ2EE engine 6.20 the export generates three files. One key file and two certificate ( CER files ) which represent the certificate chain of the server certificate. If you choose a self signed certificate you will only get one CER file from the export process. For certain SAPJ2EE installations the export creates files without a file extension. In this case you have to add the file extension CER manually.


34/43

o The CER file representing the CA root part of the server certificate should be further used for an import into the client PSE file. Copy this CER file to c:\sec\ca.cer. If you choose a self signed certificate you need to copy this CER file to c:\sec\ca.cer.

Then the client and server PSE files have to be created. The PSE file represent the keystores for the ISAPI module. We have to create a client and a server keystore for the ISAPI module. Therefore we have to open a DOS prompt at C:\sec.

o First create the client PSE with the following command :

sapgenpse.exe gen_pse -p SAPSSLC.pse "CN=myName,O=myCompany, C=myContryCode" (e.g. C=DE)

o After that create the server PSE file with the following command :

Sapgenpse.exe gen_pse -p SAPSSLS.pse "CN=myName,O=myCompany, C=myContryCode"

In both cases choose an empty password when prompted.

After creating the PSE files we have to initialise the PSE files for further usage.

o Initialise the client PSE by entering the following command :

sapgenpse.exe seclogin p C:\sec\SAPSSLC.pse

and after that authorize your action with your pin (empty password).

o Initialise the server PSE by entering the following command :

sapgenpse.exe seclogin p C:\sec\SAPSSLS.pse

and after that authorize your action with your pin (empty password).

In both cases there should be no error message. If there is an error message check if your ticket and credential file (cred_v2) is located in the same directory or if the PSE files are corrupt. Check if the sapcrypto.dll is in the same directory too.

Now we have to grant the LocalSystem NT user account access to the PSE files. This step is required because the IIS server process runs in the LocalSystem account.


35/43

o The following commands have to be executed from a DOS prompt to grant the LocalSystem account access to the PSE files:

sapgenpse.exe seclogin -p SAPSSLC.pse -O SYSTEM

sapgenpse.exe seclogin -p SAPSSLS.pse -O SYSTEM

After initialisation we have to import the server certificates CA root part into the client PSE file. This is achieved by entering the following command to the command prompt. If you used self signed certificates before you have to apply the same procedure.

o C:\sec\sapgenpse.exe maintain_pk a ca.cer

If this method fails with an error messages that the SAPSSLC.pse is not found, copy the PSE files to the destination specified in the error message. After that repeat the command. If the command executes properly copy the PSE back to C:\sec. Assuming that the file ca.cer is located in c:\sec you should see the imported certificate when you type C:\sec\sapgenpse.exe maintain_pk l -v to the command prompt. Make sure that the file ca.cer only contains the CA root part of the server certificate.

Finally we can check if we are able to establish a SSL connection to the SAPJ2EE engine with a simple test client. The test application consists of a executable called ssltest.exe. The test files are located in \tools\IIS_module\ssl\TestClient. You can invoke the test with the client.bat file in this directory. If you see some HTML output at the end of the trace output of the test your SSL installation succeeded, otherwise go through the previous installation steps again very carefully. The test will only work properly if you change the connection URL in the client.bat file to your host name which matches the CN of your server certificate.

Reboot your machine again to allow the IIS to read the PSE files during runtime.

Apache web server

To gain further information on how to set up Apache to redirect certain requests and how to enable SSL just follow the documentation provided by the Apache Group and the mod_ssl on the following web sites:

http://www.apache.org http://www.modssl.org


36/43

5. Appendix A : How to sign a server certificate with Microsoft Certification Authority

This part of the document describes how we can retrieve a valid and signed SSL server certificate from the Microsoft Certification Authority. The Microsoft Certification Authority can be installed as an optional package with Windows 2000 Advanced Server Edition. For installation details refer to the Windows 2000 AS installation guides.

After the installation of the MS CA service we are able to reach our certificate authority with a browser. The URL is http://myserver/certsrv. You should see the following welcome screen.


37/43

To request a certificate select the Request a certificate radio button and press Next.

Choose Advanced request and press the Next button again.


38/43

Choose the Submit a certificate request.. radio button and click Next.


39/43

Paste the content of the CSR file generated by the SAPJ2EE engine into the appropriate text area field and press the Submit button.


40/43

The CA confirms your request with the following screen.

Now you have to login to the machine where the MS CA is installed and open the MMC Certification Authority snap in and you should see the following window.


41/43

Select the Pending Request node and right click the pending certificate that you originally requested and issue the certificate.

Now the certificate is issued and can be downloaded from the CAs web site. Just open your browser and browse to the web site of the MS CA again. You should see the welcome screen again but instead of requesting a certificate you check on a pending certificate.


42/43

Select your request in the listbox and press the Next button.

If the certificate request is issued by the CA you should see the following browser window.


43/43

Now you are able to download your signed SSL server certificate. You have to import this certificate into the SAPJ2EE engine as described in the first chapters.

Documents

Ssl