Generating and exporting a key pair and a certificate for Data Gate

An additional key pair and certificate is required for each Data Gate instance that connects to Db2 for z/OS.

Before you begin

A Data Gate instance requires the RSA key pair and the associated certificate in a PKCS#12 password-encrypted file. You can use your tool of choice or an external certificate authority to generate the PKCS#12 file. This topic contains instructions how to generate the PKCS#12 file that uses the z/OS® Security Server RACF® RACDCERT command.

See RACDCERT GENCERT (Generate certificate) for information about the authorizations that are required to run the RADCERT command.

About this task

The steps in this section do not require or cause an outage of the system.

Note: After Data Gate service version 5.2.0, you might need to follow the instructions in Failed to extract certificates from the PKCS12 certificate file to convert the certificate with valid cipher in openssl 3.0.

Procedure

Create a JCL job and add commands to generate a pair of keys and a certificate to contain the public key for a Data Gate instance so that the z/OS client LPAR can identify the Data Gate instance as an authorized participant in the encrypted network communication.

See the following example:

//*                                                                  
//* Create a personal certificate for the ACC148 accelerator                 
//* signed by the CA                                                              
//CRKEY   EXEC PGM=IKJEFT01                                          
//SYSTSPRT DD SYSOUT=*                                               
//SYSPRINT DD SYSOUT=*                                               
//SYSTSIN  DD *                                                      
 RACDCERT ID(DB2USER) GENCERT                                +          
     SUBJECTSDN(CN('ACC148')     +                                   
     O('IBM DEUTSCHLAND RESEARCH & DEVELOPMENT GMBH')    +           
     OU('SYSTEM Z SW TESTLAB')                            +          
     L('BOEBLINGEN') SP('BADEN WUERTTEMBERG') C('DE'))    +          
     NOTAFTER(DATE(2030-12-31))                           +          
     SIZE(2048)      WITHLABEL('ACC148TTLS')              +          
     KEYUSAGE(HANDSHAKE) +                                           
     SIGNWITH(CERTAUTH LABEL('DB2 SERVER CA')) +                    
                                
/*

In this example, a key pair and a certificate with an alias name of ACC148TTLS ( WITHLABEL('ACC148TTLS')) are created. An alias (or X.509 friendly name) is required to refer to the certificate when you enable TLS communication. The certificate is signed by a certificate authority (CA) named Db2 SERVER CA.

Add commands to the JCL that will store the key pair and the certificate in a PKCS#12 file that can be transferred and read by the Data Gate instance, for example:
```
//* run a second command                                             
//CONN    EXEC PGM=IKJEFT01                                          
//SYSTSPRT DD SYSOUT=*                                               
//SYSPRINT DD SYSOUT=* 
//* export the key pair and certificate into a PKCS#12 file 
//* that can be transferred to the Data Gate instance                                              
//SYSTSIN  DD *                                                             
 RACDCERT EXPORT(label('ACC148TTLS')) ID(DB2USER)    +                  
 DSN('DGSVT2.P12') FORMAT(PKCS12DER) PASSWORD('PASSWORD')
/*
```
Important:
- The file type of the certificate file is PKCS#12, but the format you need to select when generating files of this type is PKCS12DER.
- Keep the password of the PKCS#12 file secret. Everyone who has access to the file and the password can access the private key for the authentication of the TLS connection and thus use the key to run an attack on the encrypted traffic.
- Nearly all Latin keyboard characters are allowed for the password of the PKCS#12 file:
  - a-z
  - A-Z
  - 0-9
  - The following special characters:
    
    ! Exclamation mark
    
    " Double quotation mark
    
    # Hash or pound symbol
    
    $ Dollar symbol
    
    % Percent symbol
    
    & Ampersand
    
    ' Apostrophe or single quotation mark
    
    ( Left parenthesis
    
    ) Right parenthesis
    
    * Asterisk
    
    + Plus symbol
    
    , Comma
    
    - Hyphen or minus symbol
    
    . Period or dot
    
    / Slash or forward slash
    
    : Colon
    
    ; Semicolon
    
    < Less than symbol
    
    = Equal symbol
    
    > Greater than symbol
    
    ? Question mark
    
    @ At symbol
    
    [ Left square bracket
    
    \ Backslash
    
    ] Right square bracket
    
    ^ Caret or circumflex accent
    
    _ Underscore
    
    { Left curly brace
    
    | Vertical bar or pipe symbol
    
    } Right curly brace
    
    ~ Tilde
    
    Note: The actual set of supported characters can vary depending on the version of OpenSSL and on any configuration settings that might be used.
Submit the job.
The result is a sequential data set.
Download the binary PKCS#12 certificate file to your computer so that it can be uploaded to Data Gate from the Data Gate service on IBM Cloud Pak for Data. The file name dgsvt2.p12 is used for the downloaded file in this example.