Debug SSL handshake errors with keyrings and certificates

Products

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

Issue/Introduction

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.

Environment

Release:
Component: ACF2MS

Resolution

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:

SECTRACE SET,ID=mytrace,TYPE=OMVS,SFUNC=RDATALIB,END

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:

KEYRING LDAPXXXRing

and certificates:

CERTAUTH certificate with label: USER001 CA

PERSONAL certificate with label: LDAPServer

Notes:

Look for R_datalib calls
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.
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:

Correct Ring Name for Keyring
Correct Usage for CERTAUTH and Personal Certificates
Correct labels for all certificates
If there is a certificate specified in the Keyring as DEFAULT, the certificate should be flagged as *Default*
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 with‘Priv 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:

ACF
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.