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

Why and when to perform this task

If you intend to use the Secure Sockets Layer (SSL) transport (also known as HTTPS), in addition to a distributed platform plug-in file, you must also install the Global Security Kit (GSKit) on the workstation hosting your 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. Add the GSKit installation directory to the Web server's PATH statement.
  2. Do a file search on the workstation hosting the Application Server to find the appropriate GSKit installation file for the workstation that is hosting your Web server, and move it to the GSKit installation directory you created in the previous step.
    If the workstation hosting the Application Server is different from the workstation hosting the Web Server, you will need to use FTP or another file transfer mechanism to download, in binary format, this file to the workstation hosting the Web server.
  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.
      2. Create a new key database file. Click Key Database File > New. Then specify settings:
        • Key database type: JKS
        • File Name: appServerKeys.jks
        • Location: path _to_your_ keys_directory

        Click OK.

      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. Reference the key file in the administrative console.

      Reference the appropriate SSL key file in the default SSL settings configuration panel or in the HTTPS SSL settings configuration panel. Using the default SSL settings panel, you would:

      1. Start the administrative console.
      2. Open the Security Center.
      3. Specify settings in the default SSL configuration:
        • Key File Name: fully_qualified_file_nameappserver.jks
        • Key File Password: enter your password
        • Key File Format: JKS
        • Trust File Name: (empty)
        • Trust File Password: (empty)
        • Client Authentication: selected

    4. Modify the Web server plug-in configuration file to indicate that you are using an HTTPS internal transport, and to add the keyring and stashfile properties to the definition of this internal transport.

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

      <ServerCluster Name="Servers">
      <ClusterAddress Name="ClusterAddr">
      <Transport Hostname="192.168.1.2" Port="9080" Protocol="HTTP"/>
      <Transport Hostname="192.168.1.2" Port="9443" Protocol="HTTPS">
      <Property Name="Keyring" value="c:/WebSphere/AppServer/keys/keyring.kdb"/>
      <Property Name="Stashfile" value="c:/WebSphere/AppServer/keys/keyring.sth"/>
      </ClusterAddress>
      <Server Name="Server1">
      <Transport Hostname="192.168.1.3" Port="9080" Protocol="HTTP"/>
      <Transport Hostname="192.168.1.3" Port="9443" Protocol="HTTPS">
      <Property Name="Keyring" value="c:/WebSphere/AppServer/keys/keyring.kdb"/>
      <Property Name="Stashfile" value="c:/WebSphere/AppServer/keys/keyring.sth"/>
      </Server>
      <Server Name="Server2">
      <Transport Hostname="192.168.1.4" Port="9080" Protocol="HTTP"/>
      <Transport Hostname="192.168.1.4" Port="9443" Protocol="HTTPS">
      <Property Name="Keyring" value="c:/WebSphere/AppServer/keys/keyring.kdb"/>
      <Property Name="Stashfile" value="c:/WebSphere/AppServer/keys/keyring.sth"/>
      </Server>
      <Server Name="Server3">
      <Transport Hostname="192.168.1.5" Port="9080" Protocol="HTTP"/>
      <Transport Hostname="192.168.1.5" Port="9443" Protocol="HTTPS">
      <Property Name="Keyring" value="c:/WebSphere/AppServer/keys/keyring.kdb"/>
      <Property Name="Stashfile" value="c:/WebSphere/AppServer/keys/keyring.sth"/>
      </Server>
      <PrimaryServers>
      <Server Name="Server1"/>
      <Server Name="Server2"/>
      </PrimaryServers>
      <BackupServers>
      <Server Name="Server3"/>
      </BackupServers>
      </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. 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
Configuring Web server plug-ins



Searchable topic ID:   trun_plugin_installgskit
Last updated: Jun 21, 2007 4:55:42 PM CDT    WebSphere Application Server Network Deployment, Version 5.0.2
http://publib.boulder.ibm.com/infocenter/wasinfo/index.jsp?topic=/com.ibm.websphere.nd.doc/info/ae/ae/trun_plugin_installgskit.html

Library | Support | Terms of Use | Feedback