IBM Support

Host connection emulator in IBM Developer for z/OS fails to connect to the host when encrypted connection is used

Troubleshooting


Problem

In IBM Developer for z/OS, the Host Connection Emulator fails to connect to the host when a secured connection is configured.

Symptom

Host connection emulator shows  an error such as:
Connection to host XYZ.IBM.COM failed.
hce failure

Cause

Possible causes are:
 
  • "SSL Enabled" is not checked on the configuration of the Host Connection Emulator while the host port requires secured communication.
  • Incorrect security protocol configured, like SSL instead of TLS
  • Missing certificate in the keystore selected, either from the Remote Systems Explorer or in MSCAPI
  • Incompatible cipher suite used

Environment

z/os

Diagnosing The Problem

1) Enable Client JSSE traces
Follow the MustGather document from the "Related Information" section to enable the client console log and reveal the exact problem.
2) Check for possible missing certificates
Client console log
*** ServerHello, TLSv1.2
...
*** Certificate chain

...

no trusted cert can be found
CheckServertrusted : exception caught No trusted certificate found
...
Thread-40, called closeSocket()
Thread-40, handling exception: javax.net.ssl.SSLHandshakeException: com.ibm.jsse2.util.h: No trusted certificate found
SSLHandshakeException Message: com.ibm.jsse2.util.h: No trusted certificate found
HODJSSEImpl::createSocket:2 ; server certificate not trusted : XYZ.IBM.COM:992
HODJSSEImplinitclientCertificateKeyStore : the keystore is either empty or Java has not been able to read the keystore correctly, so please re-select.
ECLErr@com.ibm.eNetwork.security.ssl.HODJSSEImpl:initClientCertificateKeyStore():5:sev=3:ECL0033: No valid client certificate was found in file or URL .
3) Check the log for possible cipher suite incompatibility
Client and host needs to have at least one cipher suite in common.
Client console log
HODJSSEImpl.configureSSLSocket : Enabled ciphers : [<list of ciphers>]
...
*** ClientHello, TLSv1.2
...
Thread-31, READ: TLSv1.2 Alert, length = 2
Thread-31, RECV TLSv1.2 ALERT:  fatal, handshake_failure
%% Invalidated:  [Session-3, SSL_NULL_WITH_NULL_NULL]
Thread-31, called closeSocket()
Thread-31, handling exception: javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure
SSLHandshakeException Message: Received fatal alert: handshake_failure
javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure
The server certificate chain is null
Host syslog
EZD1287I TTLS Error RC:  402 Initial Handshake 395
For this last example, z/OS® documentation shows that return code 402 means "No SSL cipher specifications". 

Resolving The Problem

Missing certificates

To add missing certificates depending on what type of keystore is being used:
 
Configuration Traces Location
Default keystore
HCE default keystore
Using JSSE
loading custom truststore : path = C:\idz\workspace\.metadata\.plugins\org.eclipse.rse.dstore.security\dstorekeystore.dat
File path is indicated on the traces and its content can be seen on the IDz preferences, menu
Window > Preferences > Remote Systems > SSL/TLS
HCE keystore preferences
Custom Certificate Store
HCE custom CA
loading custom truststore : path = C:\mydata\cases\xyz_keystore.jks
File path is indicated on the traces and its content can be seen in
<IDz path>\jdk\jre\bin\ikeyman.exe
HCE ikeyman
MSCAPI
HCE mscapi
HODJSSEImpl.initContext : browser keystore
Certificates are stored under Personal in the Windows MY keystore.
It can be checked using command:
certmgr /s my
certmgr
cert
Note:   The Host Connection Emulator keeps previous connection attempts in memory so you can see a combination of these traces in the log.
For example, if you connect with MSCAPI disabled first and enabled after then default and MSCAPI traces can be found in the log.
Restart IDz to see only the latest configuration.
Incompatible cipher suite
You can add a cipher suite on the Host Connection Emulator configuration by clicking the button "Use Custom Cipher".
HCE custom Cipher
The new cipher suite appears in the console log:
HODJSSEImpl.performCipherCustomization() 1: Entered : custom cipher html param :Add:SSL_RSA_WITH_3DES_EDE_CBC_SHA

Document Location

Worldwide

[{"Type":"MASTER","Line of Business":{"code":"LOB35","label":"Mainframe SW"},"Business Unit":{"code":"BU058","label":"IBM Infrastructure w\/TPS"},"Product":{"code":"SSTRMM","label":"IBM Developer for z\/OS"},"ARM Category":[{"code":"a8m0z00000009P1AAI","label":"IBM Developer for Z\/OS-\u003EHost Connect emulator (HCE) (deprecated)"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"All Versions"}]

Product Synonym

IDz

Document Information

Modified date:
03 December 2023

UID

ibm16353425

Page Feedback