Troubleshooting CWI SSL

If you are having problems setting up CWI SSL, it can be useful to test your certificates completely separately from Enterprise Server. For example, you can check the contents of a certificate with the openssl command:

openssl x509 -in file.pem -noout -text

You can also use openssl s_server and openssl s_client as simple SSL servers and clients to verify that there are no problems with your certificates.

TCPIPSERVICE startup failures

If your server certificates are valid and you are having problems starting up a TCPIPSERVICE then check in the console log for failure messages. Possible messages and suggested corrective actions include:

CASSI1010W Error environment variable ES_CERTIFICATES_LOCATION not set or pointing to an invalid location: Ensure that the environment variable ES_CERTIFICATES_LOCATION is set and pointing at a valid location.
CASSI1011W TCPIPSERVICE <TCPIPSERVICE name> could not be started. Certificate <server certificate> could not be found: Ensure that the server certificate filename (excluding the extension) matches the certificate label specified in the TCPIPSERVICE and is in the directory referenced by the value of the ES_CERTIFICATES_LOCATION environment variable. If a certificate is not specified in the TCPIPSERVICE, then the server certificate filename should match the value of the environment variable ES_DFLT_CERTIFICATE_NAME_SERVER.
CASSI1012W Error no certificate specified for TCPIPSERVICE <TCPIPSERVICE name> and ES_DFLT_CERTIFICATE_NAME_SERVER not set: Ensure that a server certificate is specified in the TCPIPSERVICE or by the environment variable ES_DFLT_CERTIFICATE_NAME_SERVER. Do not specify the file extension for the certificate.
CASSI1013W Error TCPIPSERVICE <TCPIPSERVICE name> could not be started. No passphrase for server certificate <server certificate>: Ensure that ESCERTPAS.CBL returns the passphrase for the server certificate key file when the server certificate is provided as input. ESCERTPAS.CBL should be compiled and replace the binary distributed with the product.
CASSI1014W No CA root file provided to validate client certificates for TCPIPSERVICE <TCPIPSERVICE name>. Server certificate is <server certificate>: This message doesn't imply that a TCPIPSERVICE failed to start. It simply means that client authentication cannot take place - which may be what you intended.
CASSI1015W TCPIPSERVICE <TCPIPSERVICE name> could not be started. Keyfile <server certificate key file> could not be found: Ensure that the server key file has the same name as the server certificate with _key appended, while retaining the file extension, and that it resides in the directory referenced by the value of the environment variable ES_CERTIFICATES_LOCATION.

If the TCPIPSERVICE fails to start and none of the above messages are received, then ensure that the port specified in the TCPIPSERVICE is not already in use. You should also check the log.html file in the system directory for any errors.

WEB OPEN failures

If you experience WEB OPEN failures, you should work through the following checklist:

Ensure that the TCPIPSERVICE on the server that is the target of the WEB OPEN is open.
Ensure that ESCERTPAS on the client machine will return the fully-qualified CA root file that contains the certificate used to sign the server certificate. In this case, the input certificate to ESCERTPAS will either be the client certificate being used on this WEB OPEN or spaces if no client certificate is being provided.
If the target TCPIPSERVICE requires client authentication, ensure that:
- Either a client certificate is specified on he WEB OPEN (explicitly or in the URIMAP if one is specified) or ES_DFLT_CERTIFICATE_NAME_CLIENT is set to the name of your client certificate (without the file extension) on your CICS client machine.
- The value for ES_CERTIFICATES_LOCATION on your CICS client machine is set to the directory which contains your client certificate.
- The client certificate has a key file with the same name with _key appended, and it resides in the same directory as the client certificate.
- ESCERTPAS on your CICS client machine will return the passphrase for the client certificate key file when the client certificate name is provided as input.
- ESCERTPAS on your CICS server machine must have returned a full-qualified CA root file which contains a certificate used to sign the client certificate being used on this WEB OPEN when the TCPIPSERVICE started up. In this case, the server certificate would have been the input to ESCERTPAS.

If there are still problems, check log.html for further errors.

Browser failures

Most browser failures are caused by certificate problems.

Ensure that the CA root certificate used to sign the server certificate has been installed in the browser.
If the target TCPIPSERVICE requires client authentication, ensure that your client certificate has been installed in your browser.

Diagnostics

If you are experiencing further CWI SSL issues and have exhausted the above options, there are several ways in which you can collect diagnostics to help you understand the problem:

The console log will show warning messages if any TCPIPSERVICE failed to open at region startup.
The communications log - log.html - is a good place to check if something does not seem to be working properly.
CCI tracing can be used to collect some SSL traces. Create a CCI.INI file and copy it to the current directory of the MFCS process. On Windows this is usually %WINDIR%, on UNIX you can use /proc/pid/cwd with the PID of the mfcs32 process:
```
[ccitcp-base]
ssl_display_options_on=yes
ssl_display_cert_connection_details=yes
ssl_display_destination=c:\tmp\cci-ssl-info.txt
```
You can also use CCI.INI to enable CTF tracing for CCI, in conjunction with the usual CTF configuration file. The CCI.INI section would look like:
```
[ccitrace-base]
force_trace_on=yes
data_trace=no
protocol_trace=yes
internal_net_api=yes
```
and the CTF configuration file would include:
```
mftrace.dest=binfile
mftrace.emitter.binfile#Location = path
mftrace.emitter.es#level = 99999
mftrace.level.mf.cci = info
```
Finally, you would set your MFTRACE environment variable to point to the CTF configuration file.

CCI Tracing can also be used to collect some SSL traces by adding the following to the CCI.INI file:

[ccitcp-base]
# Display the negotiated cipher
ssl_display_cipher=yes
# Display details of the peer certificate (if any)
ssl_display_cert=yes
# Display why the certificate content failed its trust test.
ssl_display_cert_fail_report=yes
# Display all details available about the offered certificate.
ssl_display_cert_connection_details=yes
# Switch on or off the SSL options above
ssl_display_options_on=yes
# Where to save the certificate information
ssl_display_destination=/home/diags/tls.txt