If you are having problems setting up CWI SSL, it can be useful to test your certificates completely separately from
. For example, you can check the contents of a certificate with the
openssl x509 -in file.pem -noout -text
You can also use
as simple SSL servers and clients to verify that there aren't any 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
- 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
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
If there are still problems, check
for further errors.
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
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 doesn't 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:
ssl_display_destination=c:\tmp\cci-ssl-info.txtYou 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:
internal_net_api=yesand the CTF configuration file would include:
mftrace.emitter.binfile#Location = path
mftrace.emitter.es#level = 99999
mftrace.level.mf.cci = infoFinally, you would set your
MFTRACE environment variable to point to the CTF configuration file.