XCOM SYSconfig.cnf file KEYRING_FILE and KEYRING_PW for SAF keyrings

Products

• XCOM Data Transport
• XCOM Data Transport - Windows
• XCOM Data Transport - Linux PC
• XCOM Data Transport - z/OS

Issue/Introduction

Using XCOM with IBM's SystemSSL in Z/OS to perform encrypted (SSL) transfers. 
Storing certificates and private keys in a SAF keyring managed by the Z/OS security product (RACF, Top Secret or ACF2)
Should the KEYRING_PW  section in the SYSconfig.cnf file have a value in this case?
For reference, the sample SystemSSL configuration file delivered by XCOM install contains:

[KEYRING_PW]        
INITIATE_SIDE = password
RECEIVE_SIDE  = password

Environment

Release: 12.0
Component: XCMVS

Resolution

Parameters in the [KEYRING_PW] section must be left empty in order to have SystemSSL retrieve the certificates and keys from a SAF keyring.

If any value is entered in this section, SystemSSL will try to access a key database file (using the name specified in KEYRING_FILE section) and the transfer will fail as that file does not exist.

Additional Information

When initializing the SystemSSL connection, CA XCOM passes the  values set in KEYRING_FILE  and KEYRING_PW  sections to the IBM System SSL API as attributes GSK_KEYRING_FILE  and GSK_KEYRING_PW.

As per IBM manual Z/OS Cryptographic Services System SSL Programming, GSK_KEYRING_FILE is interpreted as either: 

• A keystore database file (only when GSK_KEYRING_PW is also set)
• A SAF keyring specified as "userid/keyring" (if GSK_KEYRING_PW is not set)
• A PKCS #11 token if specified as "*TOKEN*/token-name"  (also if KEYRING_PW is not set)

GSK_KEYRING_PW is the key used to decrypt the keystore database file and implies that a keystore file is going to be used.
If KEYRING_PW is mistakenly set in this situation, we can expect to receive below error message from XCOM:
XCOMM1510E System SSL: gsk_environment_init(env_handle): RC = 202: Reason = Error detected while opening the certificate database