Installing a Global Security Kit for a Web server plug-in

Why and when to perform this task

If you are setting up communication between a Web server running on a distributed platform and the WebSphere Application Server for z/OS produc, and you intend to use the Secure Sockets Layer (SSL) transport (also known as HTTPS), in addition to the distributed platform plug-in file, you must also install the Global Security Kit (GSKit) on the workstation hosting this Web server. This kit helps the Web server connect to your Application Server

A CD-ROM provided with the WebSphere Application Server for z/OS product includes a GSKit installation image for each supported distributed platform. (The GSKit image is the same for all Web servers running on that platform.) Gskit install image files provides a list of the GSKit files by supported operating system.

To Install the GSKit installation image to the workstation on which the Web server is running:

Steps for this task

  1. Use the CD-ROM provided with the WebSphere Application Server for z/OS product to install the appropriate GSKit installation image file on the workstation that is hosting your Web server.
  2. Add the GSKit installation directory to the Web server's PATH statement.
  3. Using the native install process for the operating system you are running on your workstation, install this file onto workstation hosting the Web server.
    For example, DSMIT should be run on AIX, or the gsk5bas.exe, which invokes InstallShield, should be run on a Windows system.
  4. Configure the Web server for SSL support.
    See your Web server documentation for a description of how to configure SSL for your specific Web server.

    For an IBM HTTP Server for distributed platforms, you must also add the following lines to the bottom of the Web server httpd.conf file:

    LoadModule ibm_ssl_module modules/IBMModuleSSL128.dll  
    Listen port_number 
    Keyfile C:\ssl\http_session\plug-inKeys.kdb
    <VirtualHost virtual_host_name:port_number>
          ServerName virtual_host_name
          SSLEnable
          SSLClientAuth none
    </VirtualHost> 

    These lines cause the Web server to listen on the specified port.

    SSLClientAuth none indicates that you do not want to enable client authentication. If you want to use client authentication, change this line to SSLClientAuth enable.

    This change causes the HTTP Server to send a request for a certificate to the browser. Your browser might prompt you to choose a certificate to send to the Web server for performing client authentication.

  5. Create an SSL key file for the Web server plug-in.
    The content of this file depends on whom you want to allow to communicate directly with the application server over the port number specified for the HTTPS internal transport. It defines the HTTPS server security policy. The following procedure describes how to create an SSL key file with a restrictive security policy in which only the WebSphere plug-ins for the Web server are allowed to connect to the application server HTTPS internal transport:

    1. Create an SSL key file without the default signer certificates.
      1. Start IKeyMan. (See the WebSphere Application Server Network Deployment version of the Information Center for a description of how to Start IKeyMan.)
      2. The Customization Dialog created a self signed certificate authority certificate WebSphereCA. Export this certificate from the SAF database and add it to the key file on the platform where the plug-in will be running.
      3. Enter a password (twice for confirmation) and click OK.
      4. Delete all of the signer certificates.
      5. Click Signer Certificates > Personal Certificates.
      6. Add a new self-signed certificate. Click New Self-Signed to add a self-signed certificate. Specify settings:
        • Key Label: appServerTest
        • Organization: IBM

        Click OK.

      7. Extract the certificate from this self-signed certificate so that you can import it into the plug-in SSL key file.
        • Click Extract Certificate. Specify settings:
          • Data Type: Base64-encoded ASCII data
          • Certificate file name: appServer.arm
          • Location: path_to_your_keys_directory

          Click OK.

      8. Import the plug-in certificate. Click Personal Certificates > Signer Certificates > Add. Specify settings:
        • Data Type: Base64-encoded ASCII data
        • Certificate file name: appServer.arm
        • Location: path_to_your_keys_directory

        Click OK.

      9. Enter plug-in for the label and click OK.
      10. Click Key Database File > Exit.
    2. Add the application server signer certificate to the plug-in SSL key file.
      1. Start the key management utility.
      2. Click Key Database File > Open.
      3. Select the file fully_qualified_pathplug-inKeys.kdb.

        The plug-inKeys.kdb file is the key database file, that contains the public keys, private keys, trusted CAs, and certificates for the Web server plug-ins.

        Note: The default password for viewing the plugin-key.kdb using iKeyMan is WebAS.

      4. Enter the associated password and click OK.
      5. Click Personal Certificates > Signer Certificates.
      6. Click Add. Then specify settings:
        • Data Type: Base64-encoded ASCII data
        • Certificate File Name: appServer.arm
        • Location: path_to_your_keys_directory
      7. Click OK.
      8. Click Key Database File > Exit.
    3. Manually update the Web server plug-in configuration file to indicate that you are using an HTTPS transport, and to add the keyring and stashfile properties to the definition of this transport.

      Example: The ServerCluster definition for cluster Cluster1 with servers SY1_ClusterMember1, and SY1_ClusterMember2 defined, looks like the following:

      <ServerCluster CloneSeparatorChange="false"
              LoadBalance="Round Robin" Name="Cluster1"
              PostSizeLimit="10000000" RemoveSpecialHeaders="true" 
                   RetryInterval="60">
      <Server
      CloneID="BA36BEC1EB243D8B000000E4000000030926301B"
                  ConnectTimeout="0" ExtendedHandshake="false"
                  LoadBalanceWeight="2" MaxConnections="0"
                  Name="SY1_ClusterMember1" WaitForContinue="false">
      <Transport Hostname="BOSSXXXX.PLEX1.L2.IBM.COM" Port="9084" Protocol="http"/>
      <Transport Hostname="BOSSXXXX.PLEX1.L2.IBM.COM" Port="0" Protocol="https">
      <Property Name="Keyring" value="/WebSphere/V6R0M0/DeploymentManager/etc/
                  plugin-key.kdb"/>
      <Property Name="Stashfile" value=""/WebSphere/V6R0M0/DeploymentManager/etc/
                  plugin-key.sth"/>
      <Property Name="certLabel" Value="selfsigned"/>
      </Transport>
      </Server>
      <Server CloneID="BA36BED017FDF40E000000E4000000030926301B"
                  ConnectTimeout="0" ExtendedHandshake="false"
                  LoadBalanceWeight="2" MaxConnections="0"
                  Name="SY1_ClusterMember2" WaitForContinue="false">
      <Transport Hostname="BOSSXXXX.PLEX1.L2.IBM.COM" Port="9085" Protocol="http"/>
      <Transport Hostname="BOSSXXXX.PLEX1.L2.IBM.COM" Port="0" Protocol="https">
      <Property Name="Keyring" value="/WebSphere/V6R0M0/DeploymentManager/etc/
                   plugin-key.kdb"/
      <Property Name="Stashfile" value="/WebSphere/V6R0M0/DeploymentManager/etc/
                   plugin-key.sth"/>
      <Property Name="certLabel" Value="selfsigned"/>
      </Transport>
      </Server>
      <PrimaryServers>
      <Server Name="Server Name="SY1_ClusterMember1"/>
      <Server Name="Server Name="SY1_ClusterMember2"/>
      </PrimaryServers>
      </ServerCluster>

      where:

      • plug-inKeys.kdb is the key database file that contains the public keys, private keys, trusted CAs, and certificates for the Web server plug-ins.file containing the keys for the plug-ins.

        Note: The default password for viewing the plugin-key.kdb file using iKeyMan is WebAS.

      • plug-inpw.sth is the stash file that contains the encrypted database password for these certificates.

      See your Web server documentation for more information about these files.

  6. Configure an HTTPS transport to listen on the port the Web server plug-in is using to redirect requests to the WebSphere Application Server Web container on your z/OS system.
    Specify this same port on a <Transport Hostname> element in the plug-in plugin-cfg.xml file. Use the administrative console to determine the port on which the internal transport is listening.
  7. Stop the application server and the Web server and start them again.

    The configuration is complete. In order to activate the configuration, stop and restart both the application server and the Web server.


Related tasks
Installing a distributed platform Web server plug-in
Configuring Web server plug-ins



Searchable topic ID:   trun_plugin_installgskit
Last updated: Jun 21, 2007 9:56:50 PM CDT    WebSphere Application Server for z/OS, Version 5.0.2
http://publib.boulder.ibm.com/infocenter/wasinfo/index.jsp?topic=/com.ibm.websphere.zseries.doc/info/zseries/ae/trun_plugin_installgskit.html

Library | Support | Terms of Use | Feedback