Using RACF key rings

The key rings that CICS® Transaction Gateway uses when establishing secure SSL connections are stored in RACF®. This provides an alternative to Java™ keystore (.jks) files stored in the zFS (a USS filesystem).

Creating and maintaining key rings

The key ring must contain a personal certificate and the certificate authority certificate used to sign it. The key ring must be accessible by the user ID under which the Gateway daemon is running.

To create and maintain RACF key rings, you can either use the RACDCERT native command or the DIGITAL CERTIFICATES AND KEY RINGS panels found under the main RACF service options panel in ISPF.

For information on creating certificates and key rings in RACF, see the IBM® z/OS® Security Server RACF Security Administrator's Guide.

Exporting certificates

The key ring that CICS Transaction Gateway uses must contain the personal certificate with its private key connected as a personal certificate. It must also contain the Certificate Authority certificate used to sign the personal certificate, attached as a CERTAUTH certificate. The use of certificates connected as SITE is not supported.

Client applications using secure SSL connections to the CICS Transaction Gateway, must add the public key from either the CICS Transaction Gateway's Certificate Authority certificate or personal certificate, as a trusted certificate, to their own keystores.

You export the Certificate Authority certificate or personal certificate to the client keystore using FTP:
  • If you export as FORMAT(CERTB64), you must FTP the file in ASCII format.
  • If you export the certificate as FORMAT(CERTDER), you must FTP the file in binary format.

Defining key rings in the configuration file

To set the RACF key ring, edit the PRODUCT section of the configuration file to:
  • Define the keyring parameter as the name of the RACF key ring (omitting the keyringpw parameter).
  • Define the esmkeyring parameter.

For more information see SSL key ring configuration.

Using RACF key rings with ECI connection factories

To use a RACF key ring with an ECI connection factory, set the keyRingClass parameter to ESM:<key ring name>. You do not need to set the keyRingPassword parameter when using a RACF key ring.

For more information see ECI resource adapter deployment parameters.

Using RACF key rings with Java applications

To use a RACF key ring with a Java application, if the user who owns the keyring is trying to open the keyring, then the user need to set the SSL Keyring name to ESM:<key ring name>, or if a different user other than the keyring owner is trying to open the keyring, then the user need to set the SSL keyring name to ESM:<keyring owner Id>%<key ring name>. You do not need to set the keyRingPassword parameter when using a RACF key ring.