Setting up client certificate authentication on z/OS

Edit online

Setting up client certificate authentication on z/OS

About this task

Restriction: Currently, this feature is available for the privileged user only, and not for the log reader user. For more information, see Installing existing certificates.

Procedure

  1. Changes to AT-TLS setup: The AT-TLS rules for the secure port need to be adapted to accept client certificates. This change is done in the environment action for the appropriate rules.
    1. Change the HandShakeRole to ServerWithClientAuth (instead of only Server).
  2. To avoid that a client certificate is now always required but a user can still connect by using userid and password, the advanced parameters for the environment action must specify ClientAuthType Full. If this rule is only used to connect with client certificates and not with userid/password, it is recommended to set this to ClientAuthType SAFCheck to enforce client certificates that are correctly associated with a user ID. A full environment action statement might look like this: 
    TTLSEnvironmentAction          Db2SslEnv
{
  TTLSKeyRingParms
  {
    Keyring                    DB2PROD/DB2KEYRING
  }
  TTLSEnvironmentAdvancedParms
  {
    TLSv1.2                    On
    TLSv1.3                    On
    HandshakeTimeout           30
	# allow userid/password as well, else set to SAFCheck
    ClientAuthType             Full
  }
  HandShakeRole                ServerWithClientAuth
  TTLSCipherParmsRef           Db2SslCipherParms
  Trace                        3
}
  3. Changes to RACF: The client certificate is used to identify a particular user ID and to authenticate that this is a valid and approved user on that system. The authentication is done only by accepting certificates that are signed by a trusted CA (certificate authority). Which CAs are trusted is defined by the CA certificates that are connected to the RACF keyring specified in the AT-TLS environment action. In the example above, it would be the DB2KEYRING for user DB2PROD. Multiple CA certificates can be connected to that keyring, and any certificate that is signed by any of these CAs will be accepted as authorized. The identification of the user ID can be achieved by two different methods:
    1. The first method (more restrictive) is to load the public key of the client certificate into RACF as a personal certificate for the target user ID. It is more restrictive because a new public key must be added to this user ID in RACF after the certificate expires. To load a public key as a personal certificate into RACF, this command can be used:
      RACDCERT ID(DB2SYNC) ADD('DB2SYNC.CLIENT.CERT.PUBKEY.D250731.PEM') -
         WITHLABEL('DB2SYNC client cert 250731')
SETR RACLIST (DIGTCERT) REFRESH
SETR RACLIST (FACILITY) REFRESH

      If this client certificate is signed by one of the CAs already listed in the Db2 keyring, this is all that is needed. If the signing CA is not yet in the Db2 keyring, it can be added with:

      RACDCERT CERTAUTH ADD('MY.CLIENT.CERT.CA.PEM') TRUST -
         WITHLABEL('My client cert CA')
RACDCERT ID(DB2PROD) CONNECT(CERTAUTH -
         LABEL('My client cert CA') -
         RING(DB2KEYRING)
SETR RACLIST (DIGTRING) REFRESH
SETR RACLIST (DIGTCERT) REFRESH
SETR RACLIST (FACILITY) REFRESH

      If the client certificate is a self-signed certificate (not recommended), then the client certificate itself needs to be added to the Db2 keyring. For example:

      RACDCERT ID(DB2PROD) CONNECT(ID(DB2SYNC) -
         LABEL('DB2SYNC client cert 250731') -
         RING(DB2KEYRING)
SETR RACLIST (DIGTRING) REFRESH
SETR RACLIST (DIGTCERT) REFRESH
SETR RACLIST (FACILITY) REFRESH
    2. A second method is to associate a client certificate with a user ID is by creating a mapping of the certificate identifier to a user ID. This continues to work even when the client certificate must be replaced because it expired. This method requires that the CA that signs the client certificate is added to the keyring associated with Db2. To create a mapping for a specific certificate identifier, this command can be used:
    SETROPTS CLASSACT(DIGTNMAP) RACLIST(DIGTNMAP)

RACDCERT ID(DB2SYNC) MAP -
   SDNFILTER('CN=DB2Sync client cert.O=IBM.L=San Jose.SP=CA.C=US') -
   WITHLABEL('DB2SYNC client cert map')

SETR RACLIST (DIGTNMAP, DIGTCRIT) REFRESH
SETR RACLIST (DIGTRING) REFRESH
SETR RACLIST (DIGTCERT) REFRESH
SETR RACLIST (FACILITY) REFRESH
    Any certificate matching this fully qualified domain name or common name and signed by a listed CA will be allowed to connect to Db2 as the associated user ID. The SDNFILTER must match the output of RACF listing such a certificate EXACTLY, otherwise it won't match. To simplify the creation of the mapping, the current certificate can be used as a template for the MAP command. For this purpose, upload the current PEM file of the public key to z/OS and specify the data set on the map command and only list the first significant key of the distinguished name. For example: 
    RACDCERT ID(DB2SYNC) -
   MAP('DB2SYNC.CLIENT.CERT.PUBKEY.D250731.PEM') - 
   SDNFILTER('CN=DB2Sync client cert') -
   WITHLABEL('DB2SYNC client cert map')

    With this method, RACF creates a full mapping filter from the existing certificate. RACF will NOT store that certificate and any subsequent certificate created that uses the same distinguished name should match as well in the future.