Keystore Tools for Edge Caching Proxy versions 6 thru 7

Resolving The Problem

1. Keystore management done at a location external to the Edge Proxy:


Support recommends considering managing your keystore files from a single location or machine where master copies of the keystore files can reside and be scheduled for backup. This is similar to WebSphere Deployment Manager concepts. The WebSphere Admin Console has a keystore tool and since the Deployment Manager holds the master configuration repository for its Cell it is the most important machine in a WebSphere environment and most likely to be getting backed up daily.

To setup a CMS type keystore for Edge CP using WebSphere Admin Console you first need to create a directory to hold your created keystore files - example:
c:\keystores\EdgeCP\
Then in the console use the SSL keystore management tool to create a 'NEW' CMS type keystore and define the path/filename - example:
c:\keystores\EdgeCP\edgekey.kdb

If you are familiar or prefer the iKeyman tool provided with the Global Security Kit component (GSK) used by Edge and other products such as IBM HTTP Server (IHS) and WebSphere Plugin for Webserver then support would recommend installing IHS on your management machine in order to use its version of the iKeyman tool. The iKeyman provided with WebSphere Application Server is usually not pre-configured to support CMS type keystores. IHS uses CMS type and may even provide a script to load the iKeyman GUI with support for CMS type. If not, it is still easier to configure IHS iKeyman to support CMS type keystores. In particular, support recommends IHS V7 because it not only contains a local copy of Java™ but now also comes with its own copy of GSK which gives the iKeyman GUI load script (iKeyman.bat/sh) a high percentage of working and starting the iKeyman GUI ready to support CMS type keystores without additional pre-configuration of iKeyman.


2. Available keystore tools for the Edge Proxy server.

Edge Caching Proxy supports HTTPS/SSL using the Global Security Kit component (GSK). GSK provides the iKeyman tool. iKeyman is Java based and requires a Java but the Caching Proxy install does not install a copy of Java for reasons that will be discussed in a later paragraph.

- IHS iKeyman

Edge is licensed and bundled under the WebSphere Network Deployment product (ND). The ND product also bundles IHS webserver.
Rather than install a Java and obtain jars to support CMS and other type keystores for the Edge CP GSK iKeyman tool, it may be quicker and easier to install IHS and use its scripts to launch an iKeyman GUI. Support often recommends this when needing to configure keystores for the proxy. In particular, support recommends IHS V7 because it not only contains a local copy of Java but now also comes with its own copy of GSK which gives the iKeyman GUI load script (iKeyman.bat/sh) a high percentage of working and starting the iKeyman GUI ready to support CMS type keystores without additional pre-configuration of iKeyman.

- Command line tools:
- gsk7capicmd
- gsk7cmd

GSK provides command line versions of iKeyman. One that requires Java and one that does not.

gsk7capicmd uses the same C API language that Edge Proxy uses and does not require a Java. There is no GUI equivalent of this command line tool. The User Guide can be found at:

ftp://public.dhe.ibm.com/software/webserver/appserv/library/v61/ihs/GSK7c_CapiCmd_UserGuide.pdf

gsk7cmd requires Java like the iKeyman GUI. The link below to the users guide has more detail beyond the scope of this technote on the many ways to invoke and call iKeyman from the GSK or Java:

IBM Global Security Kit Secure Sockets Layer Introduction and
iKeyman User's Guide:
ftp://public.dhe.ibm.com/software/webserver/appserv/library/v61/ihs/GSK7c_SSL_Ikm_Guide.pdf

Syntax example to create a CMS type keystore for Edge Proxy:

gsk7cmd -keydb -create -db <filename> -pw <password> -type cms
-expire <days> -stash

The guide above also has excellent info on SSL and certificates if you are new to SSL configurations.

- iKeyman GUI - configuring for Edge Proxy

Since WebSphere Application Server V6 was released, most products that used GSK also install a Java because there is need for the Java besides supporting iKeyman tool. The installer/uninstaller may be Java based or some other function may require a Java.

Edge install does not use the Java installer that WebSphere Application Server uses. Edge Caching Proxy has no direct requirement for Java so a Java is not installed and follows the old rules for iKeyman to obtain a separate Java for it.

Since the installed Java may be missing the IBMCMSProvider.jar file needed to provide support for CMS type keystores, the GSK installed with Caching Proxy previously provided the required provider jar files. Documentation in both the v6.1 and V7.0 Edge Caching Proxy Administration Guide still refer to finding these jars under GSK7. Changes in GSK7 have caused these jar files to be removed. In most environments keeping up with current SSL requirements means a more recent version of GSK7 is likely installed. This means the jar files will not be available and therefore the documentation in the Proxy Admin Guide to prep a Java for iKeyman becomes incorrect. The primary purpose of this technote is to discuss how to obtain the Java and jar files required to support the Java based iKeyman tool with CMStype keystore support for Edge Proxy. This was also a good chance to point out the alternate methods and tools to manage keystores.

Fortunately a perfect Java for Edge Caching Proxy is on the Edge Components install disk/image.
Edge Load Balancer does not do any SSL encryption so it does not install GSK but, the Load Balancer configuration GUI is Java based so LB installs a Java. To obtain Java for the iKeyman tool install Edge Load Balancer as well as Caching Proxy.

The provider files needed are already in the LB Java but its java.security file has not been updated to reference the IBMCMSprovider needed for Proxy keystore. You need to edit the java.security file - an example from Windows platform:

C:\Program Files\ibm\edge\lb\java\jre\lib\security\java.security

You can add the CMS provider and re-number the provider order in the file so it looks as follows:

security.provider.1=com.ibm.jsse2.IBMJSSEProvider2
security.provider.2=com.ibm.spi.IBMCMSProvider
security.provider.3=com.ibm.crypto.provider.IBMJCE
security.provider.4=com.ibm.security.jgss.IBMJGSSProvider
security.provider.5=com.ibm.security.cert.IBMCertPath
security.provider.6=com.ibm.............
................

The remaining task is as documented in the Proxy Guide:

- Remove the ibmjsse.jar and the gskikm.jar (if present) and ibmjcaprovider.jar files from your JAVA_HOME/jre/lib/ext directory. (Do not just rename these files. Remove them from the directory) You may find that some of these file are not present in the Java depending on what Java is used.

NOTE: Solaris and HP-UX platforms - removing gskikm.jar may cause problems so be sure to consult the Proxy Guide and Support and keep a copy of this file if it needs to be restored back.

Once the java.security file is updated you should be able to set a JAVA_HOME variable and launch iKeyman with gsk7ikm.exe.

Rather than set a global JAVA_HOME you may just want to create a simple script/batch file to set the JAVA_HOME and load gsk7ikm.exe . Here is an example saved under the Proxy \Bin directory on a Windows platform:

C:\Program Files\ibm\edge\cp\bin\ikeyman.bat

Set JAVA_HOME=C:\Program Files\ibm\edge\lb\java\jre
"C:\Program Files\ibm\gsk7\bin\gsk7ikm.exe"


Support recommends getting your keystore tool working and some practice with the tool before you tackle your next SSL configuration tasks.