Debug SSL handshake errors with keyrings and certificates
search cancel

Debug SSL handshake errors with keyrings and certificates


Article ID: 13028


Updated On:


ACF2 ACF2 - DB2 Option ACF2 - z/OS ACF2 - MISC


Documentation required for Keyring Certificate issues. A Keyring and its certificates for SSL are setup, but SSL handshake errors are seen, and must be debugged.


Component: ACF2MS


The best tool for debugging SSL handshake failures related to Keyring/Certificate setup issues is the ACF2 OMVS SECTRACE. 

1) Because Keyring and certificates are loaded during server initialization, the OMVS SECTRACE is set from the z/OS console prior to the server starting:


2) After re-creating the problem the SECTRACE is deleted/disabled as  follows.                                                              

      SECTRACE DELETE,ID=mytrace                                           

3) The output of UNIX System Service (OMVS) SECTRACES is defaulted to the console.

4) A Sample OMVS SECTRACE Showing the Retrieval of Keyring and Certificates:


  and certificates:

CERTAUTH certificate with label: USER001 CA                                              

PERSONAL certificate with label: LDAPServer


  1. Look for R_datalib calls
  2. The first call is a DataGetFirst which shows the Ring Name and the first certificate, expected RC 0/0:0. However, RC=8/8:48 in the ACFRPTOM report or the OMVS SECTRACE is NOT a problem. The 'get' is issued initially with a certain size buffer. If it is not big enough for the certificate then the 'get' is reissued with a larger buffer.
  3. The next calls will be a DataGetNext for each additional certificate in the Keyring until there are no more certificates and the DataGetNext gets a 8/8:44 indicating no more certificates(end of file), expected RCs 0/0:0 for all certificates except the last 8/8:44.

Things to verify:

  1. Correct Ring Name for Keyring
  2. Correct Usage for CERTAUTH and Personal Certificates
  3. Correct labels for all certificates
  4. If there is a certificate specified in the Keyring as DEFAULT, the certificate should be flagged as *Default*
  5. If this is a server keyring, the Personal certificate must have a Private Key as denoted by ‘Priv Key len’ and ‘type=’. Note that when the client is performing server authentication, only CERTAUTH certificates are relevant.

CAS2205I REQUEST=R_datalib       ,EXIT=PRE ,RC=N/A                    
CAS2206I USER=LDAPXXX ,UID=0         ,GROUP=OMVSGRP ,GID=1            
CAS2206I Function=DataGetFirst  ,Userid=                                
CAS2206I Ring Name=LDAPXXXRing                                        
CAS2206I Usage=Certauth len=029A     ptr=0C434760                      
CAS2206I Label=USER001 CA                                              
CAS2206I Subj DN len=0000004E ptr=0C42EAA8                            
CAS2206I Certificate Owner CERTAUTH                                    
CAS2206I Recd id len=00000030 Val=00.CN=MVSSYS8CA.OU=Auditing Department
CAS2205I REQUEST=R_datalib       ,EXIT=POST,RC=0/0:0    

CAS2205I REQUEST=R_datalib       ,EXIT=PRE ,RC=N/A                    
CAS2206I USER=LDAPXXX ,UID=0         ,GROUP=OMVSGRP ,GID=1            
CAS2206I Function=DataGetNext   ,Userid=                              
CAS2206I Usage=Personal len=027F     ptr=0C434760                      
CAS2206I Priv Key  len=0000027B ptr=0BC69160 type=PKCS1 Private key    
CAS2206I Label=LDAPServer                              *Default*       
CAS2206I Subj DN len=00000033 ptr=0C42EAA8                              
CAS2206I Certificate Owner LDAPXXX                                    
CAS2206I Recd id len=00000030 Val=01.CN=MVSSYS8CA.OU=Auditing Department
CAS2205I REQUEST=R_datalib       ,EXIT=POST,RC=0/0:0                   

CAS2205I REQUEST=R_datalib       ,EXIT=PRE ,RC=N/A                  
CAS2206I USER=LDAPXXX ,UID=0         ,GROUP=OMVSGRP ,GID=1          
CAS2206I Function=DataGetNext   ,Userid=                            
CAS2205I REQUEST=R_datalib       ,EXIT=POST,RC=8/8:44      

Debugging Tips

Non-zero Return Codes (except for 8/8:48) on the DataGetFirst require the ACFRPTRV report be run and reviewed, looking for RFAC violations for resource IRR.DIGTCERT.LISTRING 

If you do not see the CAS2206I message withPriv Key len’ and ‘type= run the ACFRPTRV report and check for RFAC violations for resource IRR.DIGTCERT.LIST or RRDA violations for <ringOwner>.<ringName>.LST  

If all certificates of the Keyring are not returned, verify that all certificates are not expired and that the certificates are flagged as TRUSTed by doing CHKCERTs of each certificate in the keyring.

The handshake failure could be caused but not having the complete signing chain of CERTAUTH certificates CONNECTed to the KEYRING. To verify the complete signing chain do a CHKCERT of the PERSONAL certificate with the CHAIN parameter, for example ‘CHKCERT personal.cert CHAIN’ look for the ‘Chain Information’ and the message ‘Chain is COMPLETE’ and ‘Chain contains common ring - keyring.ring’. The CHKCERT will return the complete signing CHAIN of CERTAUTH certificates, verify that all certificates are CONNECTed to the Keyring.

For further assistance contact CA and provide the following.

Server log showing the error messages related to the KEYRING/certificates.

To verify KEYRING setup: a LIST of the KEYRING that is being used is produced:

     From TSO, ACF:                  
     SET PROFILE(USER) DIV(KEYRING)                                          
     LIST ringname       

the certificate status, keys and signing chain are verified using the LIST of the KEYRING, which shows all of the certificates in the KEYRING based on CERTDATA record names.

A TSO, ACF CHKCERT CHAIN for  the personal server certificate in the KEYRING is produced as follows from TSO:  

    CHKCERT certdata.recordname  CHAIN

To verify the server task has the authority to access the Keyring and the private key of the PERSONAL certificate, run the ACFRPTRV report against the SMF active at the time of the errors.

To verify that the Keyring, certificates and PERSONAL certificate Private Key are being returned to the server: Prior to the region/started task that the KEYRING/CERTIFICATES are being used for, start the ACF2 OMVS SECTRACE as discussed above.