IBM Support

Setting up the HTTP Server plug-in with SAF keyring for WebSphere Liberty for z/OS

How To


Summary

This document describes the steps to enable SSL communication from the IBM HTTP Server on z/OS using the web server plug-in with SAF keyring to Liberty for z/OS.

The program flow is illustrated as:

IBM HTTP Server with web server plug-in for z/OS -> SSL -> WebSphere Liberty for z/OS

Objective

  1. Specify the pluginConfiguration tag in server.xml customized with the webserver, plugin, and keyring information
  2. Generate the plugin-cfg.xml configuration file
  3. Execute the RACF commands to create the plugin keyring, and connect the signer certificate to the keyring.
  4. Update httpd.conf with directives to use the plugin and plugin-cfg.xml

     

Environment

In the examples provided.
The Liberty configuration is at:
/Liberty/servers/defaultServer/server.xml
The plugin is installed at:
/usr/lpp/ihsa_zos/plugin/bin/mod_was_ap24_http.so
A symlink can be created to point to mod_was_ap24_http.so.
A symlink was not used in this setup.
The IBM HTTP Server configuration is at:
/IHSA/ApacheServer/conf/httpd.conf

The HTTP Server address space runs under ID WEBSRV
The Liberty server address space runs under ID MYLIB1
There are a total of 3 keyrings involved in this setup.
  1. HTTP Server keyring specified by keyFile in httpd.conf used for inbound/outbound SSL communication for the HTTP Server
  2. plugin keyring specified in the plugin-cfg.xml used for outbound SSL communication to the Liberty server only
  3. Liberty keyring specified in the server.xml used for inbound/outbound SSL communication for the Liberty server

This document focuses on setting up the plugin keyring, and shows which certificate from the Liberty keyring needs to be connected to the plugin keyring.

Steps

1.  Specify the pluginConfiguration tag in the server.xml customized with the webserver, plugin, and keyring information
Add the pluginConfiguration tag to the server.xml, which will have the information for generating the plugin configuration file plugin-cfg.xml used by the web server.
For example:
<pluginConfiguration 
 pluginInstallRoot="/usr/lpp/ihsa_zos/plugin"
 webserverPort="80"
 webserverSecurePort="443"
 sslKeyringLocation="safkeyring:///PluginKeyring"
 sslStashfileLocation=""
 logFileName="/IHSA/ApacheServer/logs/plugin.log" />
A minimal set of properties were chosen for this pluginConfiguration example.
The pluginConfiguration has more properties, which can be found at Web Server Plugin (pluginConfiguration).
The pluginInstallRoot is the Web server plugin installation location in the file system of the HTTP Server (web server) host.
The webserverPort and webserverSecurePort are the web server http and https ports. 
The sslKeyringLocation is the keyring defined in RACF for the web server userid. 
The sslStashfileLocation should be set to "" as this is only used when sslKeyringLocation points to key database file (kdb) in the file system. 
The logFileName is the location to write the plugin.log file.   In this example, it is written to the web server's logs directory.  
2. Generate the plugin-cfg.xml configuration file
The plugin-cfg.xml file is automatically generated in the <server.config.dir>/logs/state directory.  

In this example, the plugin was generated at:
/Liberty/servers/defaultServer/logs/state/plugin-cfg.xml
The plugin can also be generated using the pluginUtility command. 
For example, to generate the plugin in the current directory for server defaultServer
pluginUtility generate --server=defaultServer --targetpath=./plugin-cfg.xml
Additional options for generating the plugin can be found at:
The plugin-cfg.xml should contain settings reflected in the pluginConfiguration.
 <Log LogLevel="Error" Name="/IHSA/ApacheServer/logs/plugin.log"/>
 <VirtualHostGroup Name="default_host">
        <VirtualHost Name="*:80"/>
        <VirtualHost Name="*:443"/>
    </VirtualHostGroup>
<Transport Hostname="myHost.site.ibm.com" Port="8080" Protocol="http"/>
 <Transport Hostname="myHost.site.ibm.com" Port="8443" Protocol="https">
     <Property Name="keyring" Value="safkeyring:///PluginKeyring"/>
     <Property Name="stashfile" Value=""/>
 </Transport>
3. Execute the RACF commands to create the plugin keyring, and connect the signer certificate to the keyring
The web server is currently set up with a personal certificate WebPersonal signed by a signer certificate WebSigner
RACDCERT LISTRING(WebKeyring) ID(WEBSRV)
Digital ring information for user WEBSRV:
Ring:                                                                
     >WebKeyring<                                                    
Certificate Label Name             Cert Owner     USAGE      DEFAULT 
--------------------------------   ------------   --------   ------- 
WebSigner                          CERTAUTH       CERTAUTH     NO    
WebPersonal                        ID(WEBSRV)     PERSONAL     NO    
This keyring is used for inbound SSL into the web server and is specified in the httpd.conf file with directive 
KeyFile /saf WebKeyring

Additional information on the KeyFile directive can be found at
Liberty is currently set up with a personal certificate LibertyPersonal signed by a signer certificate LibertySigner
RACDCERT LISTRING(LibertyKeyring) ID(MYLIB1)
Digital ring information for user MYLIB1:  
Ring:                                                                
     >LibertyKeyring<                                                     
Certificate Label Name             Cert Owner     USAGE      DEFAULT 
--------------------------------   ------------   --------   ------- 
LibertySigner                      CERTAUTH       CERTAUTH     NO    
LibertyPersonal                    ID(MYLIB1)    PERSONAL     NO   

The keyring is used for inbound SSL into the Liberty server and is specified in the server.xml with 
<keyStore id="CellDefaultKeyStore"
       location="safkeyring:///LibertyKeyring"
       filebased="false"
       password="password"
       type="JCERACFKS"/>
 
Additional information on the Keystore can be found at:
The native plugin code runs in the web server address space and will access the keyring PluginKeyring defined for the web server ID. 
a. Connect the keyring to web server userid
RACDCERT ADDRING(PluginKeyring) ID(WEBSRV)
b. Connect the signer certificate LibertySigner to keyring PluginKeyring
RACDCERT ID(WEBSRV) CONNECT(CERTAUTH LABEL('LibertySigner') RING(PluginKeyring))
c.  Confirm the signer certificate LibertySigner is connected to the keyring PluginKeyring for userid WEBSRV
RACDCERT LISTRING(PluginKeyring) ID(WEBSRV)
Digital ring information for user WEBSRV:  
Ring:                                                                
     >PluginKeyring<                                                     
Certificate Label Name             Cert Owner     USAGE      DEFAULT 
--------------------------------   ------------   --------   ------- 
LibertySigner                      CERTAUTH       CERTAUTH     NO    
The plugin running in the web server is a client to the Liberty server, and needs to have the signer certificate on its keyring to complete the SSL handshake. 
The webserver ID WEBSRV and Liberty server ID MYLIB1 need to have READ access to FACILITY classes
IRR.DIGTCERT.LIST and IRR.DIGTCERT.LISTRING in order to access the keyring and the private key of any personal certificates on the keyring. 
For simple setups such as a single web server and a single Liberty server, the web server keyring and plugin keyring can be the same keyring under the web server ID.  This may be a desired configuration in order to reduce the number of keyrings the SAF administrator needs to maintain.

For more complex setups with a web server containing multiple virtual hosts with multiple keyring names, or if there are multiple HTTP servers with unique keyring names,  the web server keyring and plugin keyring may need to be managed as unique keyrings.
4. Update httpd.conf with directives to use the plugin and plugin-cfg.xml
Once the plugin has been generated in step 2, move the plugin-cfg.xml to a location that the web server can access.
Ensure the permissions are set so the web server can read the plugin-cfg.xml.

The plugin generated at:
/Liberty/servers/defaultServer/logs/state/plugin-cfg.xml
was moved to
/IHSA/ApacheServer/conf/plugin-cfg.xml
Update the httpd.conf file to contain the 2 directives pointing to the plugin and plugin configuration file.
LoadModule was_ap22_module "/usr/lpp/ihsa_zos/plugin/bin/mod_was_ap24_http.so"
WebSpherePluginConfig "/IHSA/ApacheServer/conf/plugin-cfg.xml"
Start the Liberty Server and web server, and invoke a url containing a Liberty context root on the http server's ssl port. 

For example, if the adminCenter-1.0 feature is enabled in Liberty, invoke the web servers https hostname (webserver.host.name) and ssl port (443) with context root adminCenter.
https://webserver.host.name:443/adminCenter
TroubleShooting:
 If a problem occurs connecting from the web server plugin to Liberty server, trace can be enabled in the plugin-cfg.xml.
Enable plugin trace
Change the LogLevel="Trace" in the plugin-cfg.xml.

For example:
<Log LogLevel="Trace" Name="/IHSA/ApacheServer/logs/plugin.log"/>

 

Additional Information

Document Location

Worldwide

[{"Type":"MASTER","Line of Business":{"code":"LOB45","label":"Automation"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SS7K4U","label":"WebSphere Application Server for z\/OS"},"ARM Category":[{"code":"a8m50000000CczLAAS","label":"IBM HTTP Server\/WebSphere Plugin-All Platforms-\u003EWebSphere HTTP Plugin-\u003EPLG.Configuration\/Questions-\u003ESSL (certificates)-\u003EOther"}],"ARM Case Number":"","Platform":[{"code":"PF035","label":"z\/OS"}],"Version":"All Versions"}]

Document Information

Modified date:
17 February 2023

UID

ibm16955603

Page Feedback