If you are not able to establish a TLS or SSL connection to the server, check the following:
keyrng command from a command
prompt. The syntax is:
keyrng x connect server_name:port_number ftp
where:
x is a generic class name.server_name is the name of the Host On-Demand
server.port_number is the port on which the server
is listening. For non-FTP connections, the default is 443. For FTP
connections, the default is 990. ftp indicates that a connection is being made
to an FTP serverPress enter at the password prompt. A list of all the certificates in the server's keyring database appears.
keyrng utility to verify the correct certificate
and validity dates. For example:
keyrng CustomizedCAs verify
keyrng command to connect to the server on the
12173 SSL port. For example:
keyrng x connect servername:12173
If you are not able to establish an SSH connection to the server, check the following:
Refer to the following COMM error messages for more information:
When starting IKEYMAN on a Host On-Demand Server on Windows 2000, an error message occurs when loading slbck.dll during startup. A Schlumberger smart card reader must first be installed and then uninstalled. Some Schlumberger entries might remain in the registry. To get rid of this message, a user must clear all Schlumber entries out of the registry, or they must edit a file in Host On-Demand.
Host On-Demand Certificate Management uses the PKCS11 interface to access smartcard functions. This interface is used mostly for creating self-signed certificates in smartcards, or downloading a certificate in a .pfx or .p12 file to a smartcard.
Before the smartcard can be accessed, additional configuration might be required. When Host On-Demand is installed, it determines if any smartcards are present in the system. Currently, Host On-Demand recognizes the IBM Security Card and the Schlumberger Reflex readers installed with the Cryptoflex Security Kit V3.0c.
IBM Certificate Management reads all its parameters from an initialization file, ikminit_hod.properties, stored in hostondemand\bin. If Host On-Demand recognizes the IBM Security Card, the following line appears in the properties file:
DEFAULT_CRYPTOGRAPHIC_MODULE=w32pk2ig.dll
This tells IBM Certificate Manager to load this dll when smartcard functions are needed.
If Host On-Demand recognizes a Schlumberger card, a line similar to the following appears in the properties file:
DEFAULT_CRYPTOGRAPHIC_MODULE=C:\\Program Files\\Schlumberger\\Smart Cards and Terminals\\Common Files\\slbck.dll
These are the only security devices that have been tested with IBM Certificate Management. If another security device implements the PKCS11 interface through a dll, you can test it by changing the name and location of the dll in the ikminit_hod.properties file.
If the security device is removed from the system, IBM Certificate Management reports the following error at startup:
Cryptographic token initialization failed.
To prevent this error, remove the DEFAULT_CRYPTOGRAPHIC_MODULE statement from the ikminit_hod.properties file.
Installing more than one smartcard on the same computer might cause Host On-Demand smartcard support to function incorrectly.
For example, if the Host On-Demand Certificate Manager cannot open the IBM Security Card and a Schlumberger smartcard was previously installed on your computer, there might be values left in your registry causing the IBM Security Card drivers to function incorrectly.
To remedy this problem, make a backup of your registry and carefully delete any of the following keys that remain after you uninstall the Schlumberger card:
When the Host On-Demand client contacts an SSL server that requests a client certificate, such as Communications Server for Windows NT, Communications Server for AIX, or Communications Server for OS/390 in client authentication mode, the Host On-Demand client might invoke the MSCAPI interface to request all available client certificates. MSCAPI returns all registered certificates, whether they are stored completely in the MSCAPI database, or are associated through MSCAPI with some security device, such as a smartcard or thumbprint reader. The list of certificates that are currently registered in a MSCAPI database can be displayed in the following way:
Any smartcard or security device that is recognized by MSIE can be used by Host On-Demand for client authentication. Certificates are usually obtained by visiting a Web page with the MSIE browser, filling out a form on the Web page, and then storing the new certificate in either the browser's database or a security device.
For example, load http://freecerts.entrust.com/webcerts/ag_browser_req.htm into the MSIE browser. Fill out the information requested, press Proceed to Step 2 and then Proceed to Step 3. At the bottom of this page is a drop down list that lets you specify where to put the certificate.
Choosing Microsoft Base Cryptographic Provider 1.0 puts the certificate into the MSCAPI database. No extra hardware is needed to access it.
Choosing Schlumberger Cryptographic Service Provider or Gemplus GemSAFE Card CSP v1.0 puts the certificate into a smartcard. If you choose this destination, the name of the certificate appears in the MSIE Certificates window; just like a certificate that has been put into the MSCAPI database. However, the certificate will only be accessible if you have plugged in the smartcard by which the certificate was downloaded to.
You should use the certificate obtained from freecerts.entrust.com for testing purposes only. After downloading the certificate, go to the the MSIE Certificates window and click the Trusted Root Certification Authorities tab. Scroll down the list until you find a certificate issued to Entrust PKI Demonstration Certificates. Highlight this certificate and export it to a file. Then add the exported file to the trusted list of your client authenticating SSL server. With this configuration, the SSL server should trust the Entrust certificate if it is returned by the Host On-Demand client. You should only use this exercise for testing purposes, and you should remove the Entrust PKI Demonstration Certificate from any production server.
Host On-Demand Certificate Management uses the PKCS11 interface to access smartcard functions. This interface is used mostly for creating self-signed certificates in smartcards, or downloading a certificate in a .pfx or .p12 file to a smartcard. (Note: The IBM Security Card supports the creation of a self-signed certificate, but not the downloading of an existing certificate in a .pfx or .p12 file.)
Before the smartcard can be accessed, additional configuration may need to be done. When Host On-Demand is installed, it tries to determine if any smartcards are present in the system. Currently the only smartcards that are recognized are the IBM Security Card and the Schlumberger Reflex readers installed with the Cryptoflex Security Kit V3.0c.
IBM Certificate Management reads all its parameters from an initialization file named ikminit_hod.properties that is stored in the hostondemand\bin directory. If the IBM Security Card was recognized, the following line will appear in the properties file:
DEFAULT_CRYPTOGRAPHIC_MODULE=w32pk2ig.dll
This tells IBM Certificate Manager to load this dll when smartcard functions are needed.
If no IBM Security Card was detected, but a Schlumberger card was, the line will be similar to
DEFAULT_CRYPTOGRAPHIC_MODULE=C:\\Program Files\\Schlumberger\\Smart Cards and Terminals\\Common Files\\slbck.dll
These are the only security devices that have been tested with IBM Certificate Management. If you have another security device that implements the PKCS11 interface through a dll, it can be tested by changing the name and location of the dll in the ikminit_hod.properties file. If the smartcards are ever removed from the system, these lines should be removed from ikminit_hod.properties.
With this configuration, a self-signed certificate can be created in the smartcard with the following steps:
Both the IBM Security Card and Schlumberger cards can create self-signed certificates. The Schlumberger card can also have a certificate in a .p12 or .pfx file imported to the card.
If self-signed certificates are created, then the public portion of the certificates must be extracted (not exported) and added to the trusted list of the SSL server that will request the certificate.
If a self-signed certificate is created in the IBM Security Card, it must be registered with MSCAPI. To do this, start the GemSAFE Card Details Tool. It will check the card, see that the certificate in the card has not been registered with MSCAPI, and ask if you want to register it.
In our testing, not all readers supported all operations on all platforms. Here is a table of what readers were tested on which platforms.
| Entrust | Self-signed | Add .p12 | Windows 98/NT operating sytem | Windows 2000 operating system | |
|---|---|---|---|---|---|
| IBM Security Card PCMCIA Reader | X | X | X | ||
| IBM Security Card Serial Reader | X | X | |||
| Schlumberger Reflex 20 Reader | X | X | X | X | X |
| Schlumberger Reflex 72 Reader | X | X | X | X | |
| Schlumberger Reflex Lite | X | X | X | X |
Host On-Demand and its utilities will not read PKCS12 files exported using the z/OS utility gskkyman. The problem is that gskkyman uses PFX v1 format for PKCS12 files, whereas Host On-Demand and its utilities use PFX v3 format for PKCS12 files.
Here is an example of a failing scenario:
Certificate password was incorrect or certificate found at <path
of PKCS12 file> was corrupted. (ECL0034) Another failing scenario may be that the certificate cannot be read by any of the Host On-Demand certificate utilities.
The fix is to convert the PKCS12 file to PFX v3 format before sending the PKCS12 file to a user and before using the PKCS12 file with any Host On-Demand utility or session. To convert the format, take the following steps:
On the Windows operating systems, after Host On-Demand is upgraded to a new level, the Certificate Wizard panel may not appear when the Certificate Wizard is started.
This problem is caused by the fact that program processes associated with the Certificate Wizard may have been left running during the upgrade. On Windows 2000 operating systems these program processes are:
As a temporary workaround, you can use the Certificate Manager.
To actually fix this problem using the Windows 2000 operating system, follow these steps:
When using Host On-Demand Versions 5 and 6 cached clients, in order to support UTF-8 encoding with the self-signed certificates created with the Host On-Demand Version 7 server, download either the 6.0.4a or 5.0.8a Interim Service Build (ISB) from the IBM Software Internet Service Delivery site at http://www6.software.ibm.com/aim/home.html. You will need to register on this site if you have not already done so.
Keytool.exe is a binary executable for Windows included with the JRE installed with Host On-Demand. When running keytool.exe, there are translation errors for the Czech Republic language.
To resolve this problem, upgrade to the latest IBM JRE on the Host On-Demand Service Key Web site.
The certificate management utility on AIX requires JRE 1.1.8. If you are
running JVM 1.3, you will receive the following error message:
Exception in thread "main" java.lang.VerifyError
To use the certificate management utility on AIX with JRE 1.1.8, set the JAVA_HOME environment variable to point to the Java 1.1.8 installation before running the "CertificateManagement" script.
When using other vendors' security products that lock or overwrite files, such as Netscape's Mission Control, be aware that the edited client configuration files may cause problems when upgrading to a newer version of Host On-Demand.
For example, if the signed.db file is locked or overwritten, the prior version of Host On-Demand's signed certificate is presented. Consequently, because the incorrect version of the certificate continues to be presented, users are prompted to grant or deny access to the newer version's Host On-Demand applets each time they try to log in. Selecting the "Remember this decision" checkbox has no effect. Other symptoms include blank lines or undefined hexadecimal certificate information in Netscape's Java/Javascript Certificate list.
To resolve this, follow the security program's instructions on how to recapture the configuration to use the newer version of Host On-Demand's signed certificate before distributing to users.
