Installing existing certificates

You might want to use certificates created by an external certificate authority (CA) or created by an internal process in your organization rather than a newly created self-signed certificate. If so, then you can omit some of the otherwise required configuration steps. Use this article as a guideline for the installation of existing certificates.

Several steps are required on the z/OS LPAR where your Db2 subsystem or data sharing group is located:

1. Create the key ring and store your certificates in it.
   See the following example:

   RACDCERT ID(DB2USER) ADDRING(DB2AKEYRING)
   RACDCERT ID(DB2USER) -
            CONNECT(CERTAUTH -
            LABEL('IBM ROOT CA') RING(DB2AKEYRING))
   RACDCERT ID(DB2USER) -
            CONNECT(CERTAUTH -
            LABEL('IBM INTERMEDIATE CA') RING(DB2AKEYRING))
   RACDCERT ID(DB2USER) -
            CONNECT(ID(DB2USER) -
            LABEL('DB2ASERVER CERTIFICATE') -
            RING(DB2AKEYRING) DEFAULT)

   To reuse the code in the example, replace:

   DB2USER

   Replace this user ID with the z/OS ID of the Db2 started task that you use to connect to Db2 Data Gate.

   DB2AKEYRING

   Replace the key ring name with a name of your own choosing.

   IBM ROOT CA

   Replace this label with the exact name of your root certificate. Keep the single quotes.

   IBM INTERMEDIATE CA

   Replace this label with the exact name of your signer certificate. Keep the single quotes.

   DB2ASERVER CERTIFICATE

   Replace this label with the name of your Db2 for z/OS server certificate. Keep the single quotes.

2. Verify that the Db2 for z/OS server certificate, the signer certificate, and the root certificate have been correctly stored in the key ring.
   You can run the following command for this purpose:

   RACDCERT LISTRING(<key ring>) ID(<user>)

   where:

   <key ring>

   Is the name of the key ring.

   <user>

   Is the ID of the user who runs the Db2 started task and owns the key ring.

   Example:

   RACDCERT LISTRING(DB2AKEYRING) ID(DB2USER)

   Here, the name of the keyring is DB2AKEYRING and the started task user and owner of the key ring is DB2USER.

   The output of the command must be similar to the output of this example:

   Digital ring information for user DB2USER:                             
                                                                          
     Ring:                                                                
          >DB2AKEYRING<                                                     
     Certificate Label Name             Cert Owner     USAGE      DEFAULT 
     --------------------------------   ------------   --------   ------- 
     IBM INTERMEDIATE CA                 CERTAUTH       CERTAUTH    NO    
     DB2ASERVER CERTIFICATE             ID(DB2USER)     PERSONAL    YES   
     IBM ROOT CA                         CERTAUTH       CERTAUTH    NO                                                                       
   

   In this example, the Db2 server certificate is DB2ASERVER CERTIFICATE, and the signer certificate is IBM INTERMEDIATE CA. The signer certificate has been issued by the IBM ROOT CA.

3. Verify that the Db2 server certificate and the signature are valid by running the following command:

   RACDCERT LISTCHAIN(LABEL('<cert>')) ID(<user>)
   

   where:

   <cert>

   Is the name (label) of the certificate

   <user>

   Is the ID of the user who runs the Db2 started task and owns the key ring

   Example:

   RACDCERT LISTCHAIN(LABEL('DB2ASERVER CERTIFICATE')) ID(DB2USER)
   

   Here, the name of the keyring is DB2ASERVER CERTIFICATE and the started task user and owner of the key ring is DB2USER.

   The LISTCHAIN command gives you ample information about the certificates in a key ring, including:

   • The number of certificates in the displayed chain
   • Whether the chain is complete or incomplete
   • Whether the chain contains any NOTRUST or expired certificates
   • The names of any common key rings to which all certificates in the chain are connected

   For more information, see RACDCERT LISTCHAIN (List certificate chain).

On the Cloud Pak for Data system where your Db2 Data Gate instances are deployed:

4. Verify that you can access the certificates on the z/OS system and show the contents of these certificates by running the following openssl command on the Cloud Pak for Data side:

   openssl s_client -connect <Db2 IP>:<Db2 port> -showcerts

   where:

   <Db2 IP>

   Is the IP address of the z/OS LPAR that hosts your Db2 subsystem or data sharing group.

   <Db2 port>

   Is the DDF secure port used for connections between the z/OS LPAR and your Db2 Data Gate instance.

5. Complete the following steps to copy and paste the contents your Db2 Data Gate certificates and the private key of the Db2 Data Gate server into a p12 certificate file:
   1. Create a file with the name dgserver.pem as shown below and paste the content of the Db2 Data Gate server certificate in this file, in the position indicated:

      -----BEGIN CERTIFICATE-----
           <DG server certificate content>
      -----END CERTIFICATE-----

   2. In the same way as in step 5.a, create a file named ca.pem that contains the root certificate and the signer certificate of your Db2 Data Gate server certificate:

      -----BEGIN CERTIFICATE-----
           <Content of root CA certificate>
      -----END CERTIFICATE-----
      -----BEGIN CERTIFICATE-----
           <Content of intermediate CA certificate>
      -----END CERTIFICATE-----

   3. Likewise, create a file named server.key to contain the private key of the Db2 Data Gate server:

      -----BEGIN PRIVATE KEY-----
           <private key>
      -----END PRIVATE KEY-----

   4. Run the following command to pack the certificate files and the private key file into a p12 file called dgcert.p12:

      openssl pkcs12 -export -inkey server.key -in dgserver.pem -certfile ca.pem -out dgcert.p12
      

   5. Enter a password for the p12 file when prompted.
   6. Verify that the p12 file has been successfully created by running the following command. Specify your password when it is requested:

      openssl pkcs12 -info -in dgcert.p12 -passin pass:<password>
      

      where <password> is the password from step 5.e.

6. To use the p12 certificate file, create or open a Db2 Data Gate instance on the Cloud Pak for Data web user interface. Select the file where it is requested, or drag it to the proper position.
   For more information, see:

   • Step 28 in Creating a Db2 Data Gate instance
   • Step 6 in Updating a source definition for Db2 Data Gate

   Repeat this step for each Db2 Data Gate instance that connects to the same Db2 subsystem or data sharing group.