Setting up client certificate authentication on z/OS

This describes how to set up client certificate authentication on z/OS.

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 using userid and password, the advanced parameters for the environment action has to 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 could 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 an approved user on that system. The authentication is done by only accepting certificates 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 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 has to be added to this user ID in RACF, once 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 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 will continue to work even when the client certificate has to 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 will create a full mapping filter from the existing certificate. RACF will NOT store that certificate and any subsequent certificate created using the same distinguished name should match as well in the future. To use the certificate, you must use the configuration UI as described in "Creating a service instance for Data Gate from the web client(step 27, Select the Source database authentication method).