Security troubleshooting checklist

If you are not able to establish a TLS or SSL connection to the server, check the following:

1. What kind of certificate do you use?
   • Self-signed
   • CA
2. Where is the certificate stored (for example, is it in the server's keyring)?
3. Have you added the certificate to the Z and I Emulator for Web server's keyring database? Issue the 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 Z and I Emulator for Web 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 server

   Press enter at the password prompt. A list of all the certificates in the server's keyring database appears.

4. Check that the password for the database file has not expired and that it is stashed.
5. If you added a certificate, check the validity dates on the certificate to determine if the certificate has expired.
6. If the certificate is still valid, add it to the Z and I Emulator for Web server keyring. Stop and restart the Service Manager.
7. Add the certificate to the client keyring to make it available to the clients.
8. Use the keyrng utility to verify the correct certificate and validity dates. For example:

   
   keyrng CustomizedCAs verify
   

9. Use the keyrng command to connect to the server on the 12173 SSL port. For example:

   
   keyrng x connect servername:12173 
   

10. Configure a TLS or SSL session on the client to connect to a server on an SSL port (such as 12173).
11. Try removing the Z and I Emulator for Web client, deleting temporary internet files, and try again. Deleting the temporary internet files removes the current CustomizedCAs.class.
12. If possible, verify connectivity by trying to connect. (See Client does not connect for troubleshooting hints.)

13. If you use a self-signed certificate, verify that the CustomizedCAs.class is present in the \zieforweb\ZIEWeb directory. If you use a self-signed certificate or a certificate issued by an unknown CA, extract the certificate and include it in the CustomizedCAs.class files. This file resides in the Z and I Emulator for Web publish directory so that the clients can get to it. It is downloaded every time the Z and I Emulator for Web client is downloaded.
14. If you experience problems with SSL on the Redirector, verify that the Z and I Emulator for Web server key database and the CustomizedCAs.class have been created and are present on the computer running the Z and I Emulator for Web Redirector. See Redirector Troubleshooting Checklist for details.

If you are not able to establish an SSH connection to the server, check the following:

1. Make sure the address and port number of the server are correct. The standard port number of SSH server is 22, but it can be different.
2. Check the JVM level on the client. Z and I Emulator for Web SSH function requires a Java 2 JVM with Java Cryptography Extension (JCE), which is a part of JCE since JDK 1.4 on client side. If you use an older JVM, for example JDK 1.1 or JDK 1.3 level of JVM without JCE, upgrade your JVM to JDK 1.4 level.
3. Make sure SSH Version 2 protocol is enabled on the server. Older SSH servers support only SSH Version 1.x protocol, which Z and I Emulator for Web does not understand.
4. If you have enabled public-key authentication, disable it and try to use password authentication only because the configuration for public-key authentication is more complicated and error-prone.
5. If password authentication works, double-check the configuration for public-key authentication. In many cases, the configuration on the server is not correct, for example file permissions. The procedure is different depending on your SSH server. For more information, refer to your SSH server documentation.
6. The private/public key-pair used for public key authentication is saved on the file system of each client. If you need to use public key authentication from more than two clients, you need to copy KeyStore file (usually it is .keystore file in user's home directory) to other machines.
7. Many SSH Servers have their own debug modes. If you have difficulties in problem identification, you might want to use them. For more information, refer to your SSH server documentation.

Refer to the following COMM error messages for more information:

1. COMM662: The signer certificate of the host's site certificate has not been added to the CustomizedCAs.class on the Z and I Emulator for Web server. This error can occur when using a self-signed certificate if you specified a password other then zieweb .
2. COMM663: The certificate on the server might use a name that does not match its Internet name.
3. COMM666: The certificate might have expired.

When starting IKEYMAN on a Z and I Emulator for Web 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 Z and I Emulator for Web.

Before the smartcard can be accessed, additional configuration might be required. When Z and I Emulator for Web is installed, it determines if any smartcards are present in the system. Currently, Z and I Emulator for Web recognizes the IBM Security Card and the Schlumberger Reflex readers installed with the Cryptoflex Security Kit V3.0c.

If Z and I Emulator for Web recognizes the IBM Security Card, the following line appears in the properties file:

DEFAULT_CRYPTOGRAPHIC_MODULE=w32pk2ig.dll

If Z and I Emulator for Web 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

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, the following error is reported 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 Z and I Emulator for Web smartcard support to function incorrectly.

For example, if the Z and I Emulator for Web 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:

• HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Calais\Readers\Schlumberger ...
• HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Calais\SmartCards\Schlumberger ...
• HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Defaults\Provider\Schlumberger ...
• HKEY_LOCAL_MACHINE\SOFTWARE\Schlumber ...

When the Z and I Emulator for Web 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 Z and I Emulator for Web 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:

1. Start the Internet Explorer 5.x browser.
2. From the menu bar, choose Tools then Internet Options.
3. Across the top of the Internet Options panel, choose the Content tab.
4. On the Content panel, click the Certificates button.
5. Across the top of the Certificates panel, choose the Personal tab; if it is not already chosen. These are the certificates that will appear in the drop down list on the Z and I Emulator for Web session configuration panel and the Server Requesting Certificate panel. If the certificate is not in this list, it cannot be used by Z and I Emulator for Web for client authentication.

Any smartcard or security device that is recognized by MSIE can be used by Z and I Emulator for Web 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 Z and I Emulator for Web client. You should only use this exercise for testing purposes, and you should remove the Entrust PKI Demonstration Certificate from any production server.

Before the smartcard can be accessed, additional configuration may need to be done. When Z and I Emulator for Web 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.

If the IBM Security Card was recognized, the following line will appear in the properties file:

    DEFAULT_CRYPTOGRAPHIC_MODULE=w32pk2ig.dll

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

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.

Both the IBM Security Card and Schlumberger cards can create self-signed certificates. The Schlumberger card can also have a certificate in a .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.

Z and I Emulator for Web 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 Z and I Emulator for Web and its utilities use PFX v3 format for PKCS12 files.

Here is an example of a failing scenario:

1. On a z/OS server, the system administrator:
   1. Uses gskkyman to create a self-signed certificate to serve as a personal certificate for a Z and I Emulator for Web client.
   2. Uses gskkyman to export the key and the certificate to a PKCS12 file. (The function on the gskkyman Export Key Menu is 'Export keys to a PKCS12 file'.
   3. Transmits the PKCS12 file to the user.
2. On the client, the user:
   1. Starts a 3270 Display session that requires that the client send a certificate to the host, and that specifies that the certificate source be a PKCS12 or PFX file.
   2. Provides, when prompted by the 3270 Display session startup program, the path of the PKCS12 file that was received from the system administrator.
   /ol for z/OS inner list
3. On the client, the 3270 Display session startup program displays the following error message: 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 Z and I Emulator for Web 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 Z and I Emulator for Web utility or session. To convert the format, take the following steps:

1. Download the certificate to a workstation that has a Netscape 4.x or Netscape 6.x browser installed.
2. Use Netscape to import the certificate from the PKCS12 file. Netscape can read the PFX v1 format. To import the file using Netscape 4.x:
   1. Click Communicator > Tools > Security Info.
   2. Under Certificates, click Yours.
   3. Click Import a Certificate... and follow the instructions to import the certificate from a PKCS12 file.
   End of inner list
3. Use Netscape to export the certificate to a PKCS12 file. Netscape will export the certificate in PFX v3 format. To export the file using Netscape 4.x:
   1. Click Communicator > Tools > Security Info.
   2. Under Certificates, click Yours.
   3. Click the imported certificate.
   4. Click Export a Certificate... and follow the instructions to export the certificate to a PKCS12 file.
4. Does Keytool.exe produce errors for the Czech Republic language?

   Keytool.exe is a binary executable for Windows included with the JRE installed with Z and I Emulator for Web. 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 Z and I Emulator for Web Service Key Web site.

5. Review Certificate management utility limitation on AIX

   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.

6. Review using Z and I Emulator for Web with other security products

   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 Z and I Emulator for Web.

   For example, if the signed.db file is locked or overwritten, the prior version of Z and I Emulator for Web'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 Z and I Emulator for Web 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 Z and I Emulator for Web's signed certificate before distributing to users.