PK78166: DOCUMENT HOW TO SETUP SSL BETWEEN THE IBM HTTP SERVER ADMINISTRATION SERVER AND THE ADMINISTRATIVE CONSOLE

APAR status

• Closed as documentation error.

Error description

• The Information Center for IBM HTTP Server Versions 6.1 and 6.0
  is incomplete. The documentation does not explain the
  configuration and process changes that are necessary to setup
  the IBM HTTP Server Administration Server with Secure Sockets
  Layer (SSL) enabled for connections with the Administration
  Console for WebSphere Application Server. This setup requires
  you to use iKeyman to create a self-signed certificate for the
  IBM HTTP Server Administration Server. Extract this
  certificate from the iKeyman key database and import it into
  the key database for the Administration Console.
  
  This information needs to be added to the information centers.
  

Local fix

• 1. Using Ikeyman
  -create SelfSigned Certificate for the  IBM Administration
  Server and
     save into the <installRoot>/conf/admin.kdb
  -note the password and check the checkBox "Stash password to a
  file"
  -Label "adminselfsigned"
  -Common Name "localhost'
  -If  selfsigned Certificate is default then no need to add  the
  following line:
   SSLServerCert adminselfSigned
  
  -Now  click "Extract Certificate"  from the ikeyman panel with
  the adminselfSigned
      certificate highlighted.
  -Do not  change the data type
  
  
  3. Start DMGR  go to the Admin console
   http://<hostname>:<adminport>/ibm/console/
  
   select -> Security-> "SSL certificate and key management"
    click " Manage endpoint security configurations"
  
  
   You will see a list of Inbound and outbound endpoints
   click on the "OUTBOUND" cell
     <cellname>(cellDefaultSSLSettings,null)
  
   Under "Related Items"
   click "Key stores and certificates"
  
   Then
   click "CellDefaultTrustStore"
   Under "Additional Properties"
   click  "signer Sertificates"
  
   In the collection panel for "Signer Certificates"
   click "add" button
  
   *Alias type-> "adminselfSigned"
   *File name -> <fully qualified path for the extracted
  certificate>
     (ie c:\program files\i bm\httpserver\conf\cert.arm)
   Do not change the data Type
  
   Save
  

Problem summary

• ****************************************************************
  * USERS AFFECTED:  This APAR affects users of IBM HTTP Server  *
  *                  with WebSphere Application Server Versions  *
  *                  6.1 and 6.0. Users are attempting to        *
  *                  configure secure socket layer (SSL)         *
  *                  communications from the IBM HTTP Server     *
  *                  Administration Server to the deployment     *
  *                  manager of the Application Server.          *
  ****************************************************************
  * PROBLEM DESCRIPTION: The Version 6.1 and 6.0 Information     *
  *                      Centers for IBM HTTP Server do not      *
  *                      include the documentation that is       *
  *                      necessary to configure SSL              *
  *                      communications between the IBM HTTP     *
  *                      Server Administration Server and        *
  *                      deployment manager for the Application  *
  *                      Server.                                 *
  ****************************************************************
  * RECOMMENDATION:                                              *
  ****************************************************************
  The Information Center for IBM HTTP Server V6.0.x and V6.1.x
  is missing documentation that explains how to configure SSL
  communications from the Application Server to IBM HTTP Server
  Administration Server.
  

Problem conclusion

• A sub-topic of the "Task overview: Securing IBM HTTP Server"
  topic will be created. The new topic will be entitled,
  "Configure SSL between the IBM HTTP Server Administration
  Server and the deployment manager."
  
  The following information will be available in the new topic:
  
  Configure Secure Sockets Layer (SSL) between the deployment
  manager for WebSphere? Application Server and the IBM? HTTP
  Server administration server, which is called adminctl.
  
  Version 6.1 of Application Server has new SSL management
  functions that need to be managed properly in order for IBM
  HTTP Server to connect with an SSL request. In earlier
  releases, SSL connections used default dummy certificates that
  were exchanged between IBM HTTP Server and the Application
  Server. In WebSphere Application Server Version 6.1, you must
  configure the Application Server to accept a self-signed
  certificate from IBM HTTP Server so SSL connections are
  accepted and transactions are completed.
  
  If the Application Server and the IBM HTTP Server
  administration server are not configured correctly, the
  Application Server shows any errors that are received in the
  log file for the deployment manager. In situations where the
  IBM HTTP Server administration server is attempting to connect
  through SSL and the Application Server is not configured, you
  might receive an error that is similar to the following message:
  -CWPKI0022E: SSL HANDSHAKE FAILURE:  A signer with
  SubjectDN "CN=localhost" was sent from target host:port
  "null:null".
  The signer may need to be added to local trust store
  "c:/619/app2/profiles/Dmgr01/config/cells/rjrCell02/trust.p12"
  located in SSL configuration alias "CellDefaultSSLSettings"
   loaded from SSL configuration file "security.xml".
  The extended error message from the SSL handshake
   exception is: "No trusted certificate found".
  
  -IOException javax.net.ssl.SSLHandshakeException:
  com.ibm.jsse2.util.h: No trusted certificate found
  
  1. Obtain a self-signed server certificate. You can generate a
     new self-signed certificate or use the existing certificate
     from the IBM HTTP Server Web server plugin.
  
      * Use the existing self-signed certificate from the IBM
        HTTP Server Web server plugin.
      * Create a CMS key database file and a self-signed server
        certificate. Use the iKeyman utility for distributed
        operating systems and the gskkyman tool for z/OS
        operating systems. This step and later steps will assume
        that you are using the iKeyman utility.
      Distributed operating systems
      Use the IBM HTTP Server iKeyman utility graphical user
      interface or command line to create a CMS key database
      file and a self-signed server certificate.
  
      Use the iKeyman utility to create a self-signed certificate
      for the IBM HTTP Server Administration Server and save the
      certificate as /conf/admin.kdb.
  
      Note: Make note of the password and select Stash password
      to a file.
      The following fields are required for the certificate:
  
      Label: adminselfSigned
      Common Name: fully_qualified_host_name
  
      z/OS operating system
      IBM HTTP Server uses the z/OS gskkyman tool for key
      management to create a CMS key database file, public and
      private key pairs, and self-signed certificates.
      Alternatively, you can create a SAF keyring in place of a
      CMS key database file.
  
      * For information on gskkyman, see Key management using
        the native z/OS key database.
      * For information on creating SAF keyrings, see
        Authenticating with SAF on IBM HTTP Server and SSL
        keyfile directive.
  2. Extract the self-signed certificate to a file using iKeyman
     utility.
     a. Select the certificate that you created in Step 1. For
        example, adminselfSigned.
     b. Click Extract Certificate. The recommended file name for
        extraction is
        C:\Program Files\IBM\HTTPServer\conf\cert.arm.
        Note: Do not change the data type.
  3. Modify the Administration Server configuration File, which
     is named admin.conf.
     a. Configure the file to load the IBM SSL module. Uncomment
        the following line:
        LoadModule ibm_ssl_module     modules/mod_ibm_ssl.so
     b. Enable SSL and define a key file to use. Uncomment the
        following lines to enable SSL and define a key file to
        use:
        SSLEnable
        SSLServerCert default
        Keyfile "C:/Program Files/IBM/HTTPServer5/conf/admin.kdb"
        Note: Be aware of the following:
        * The key file directive must match the name and location
          of a valid key file that is installed on your system.
      * You must have IBM SSL support installed for this to work.
      * The "default" in SSLServerCert is the label, or name, of
        the self-signed certificate that is created when the
        plugin-key.kdb file was created.
      * The previous example uses SSLServerCert because the
        default self-signed certificate in the plugin-key.kdb is
        not flagged as the default certificate.
  4. Start the administration server for IBM HTTP Server. Verify
     that the log file does not contain GSKIT errors.
  5. Configure WebSphere Application Server.
     a. Log into the Administrative Console for the Application
        Server and start the deployment manager.
     b. Select Security > SSL certificate and key management.
     c. Select Manage endpoint security configurations. You are
        directed to a list of inbound and outbound endpoints.
     d. Select the outbound cell (cellDefaultSSLSettings,null).
        Select outbound cells because, in this setup, the
        Administration Console for the Application Server is the
        client, and the IBM HTTP Server Administration Server is
        the server.
        Note: This setup is the opposite configuration from an
              SSL setup with the IBM HTTP Server plugin and the
              Application Server.
     e. In the Related Items section, click Key stores and
        certificates.
     f. Click CellDefaultTrustStore.
     g. In the Additional Properties section, click Signer
        Certificates.
     h. FTP the certificate file to the Application Server. Do
        not change the data type.
     i. In the collection panel for Signer Certificates, click
        Add. Enter the following information in the fields.
        Alias: adminselfSigned
        File name: file_name
           For example, enter the following:
           c:\program files\ibm\httpserver\conf\cert.arm
     j. Save the configuration changes to the administrative
        console.
     k. Stop the deployment manager.
     l. Start the deployment manager.
  
  Results
  The IBM HTTP Server administration server and Application
  Server are now configured to use SSL transactions.
  
  Related concepts
  Secure Sockets Layer (SSL) protocol
  SSL directive considerations
  Authentication
  Secure Sockets Layer environment variables
  [AIX Solaris HP-UX Linux Windows] Managing keys with the
  IKEYCMD command line interface (Distributed systems)
  
  Related tasks
  [AIX Solaris HP-UX Linux Windows] Working with key databases
  [AIX Solaris HP-UX Linux Windows] Creating a self-signed
  certificate
  [z/OS] Managing keys with the native key database gskkyman
  (z/OS systems)
  [z/OS] Authenticating with SAF on IBM HTTP Server (z/OS systems)
  
  Related reference
  SSL directives
  [AIX Solaris HP-UX Linux Windows] Managing keys with the
  IKEYMAN graphical interface (Distributed systems)
  [z/OS] SSL directives
  
  The updates to the information centers will be available
  externally in March 2009.
  

Temporary fix

Comments

APAR Information

• APAR is sysrouted FROM one or more of the following:

• APAR is sysrouted TO one or more of the following:

Fix information

Applicable component levels