Step 6: Set Up the Certificate (Key) Database

Before the SSL server can be used to secure any connections, an SSL certificate database (or, key database) must exist, and must be populated with one or more server certificates.

Only two kinds of certificate database are allowed as SSL certificate database, one is the standard key database file which has a file extension of .kdb, another is the PKCS #12 certificate store which has a file extension of .p12 or .pfx. SSL server will not support the other certificate database file name.

Use the steps that follow to create and prepare the key database file:

1. Log on the GSKADMIN user ID and allow its default PROFILE EXEC to run.

   For convenience, an IBM-supplied PROFILE EXEC has been provided for the GSKADMIN user ID that prepares a basic work environment for performing certificate database management tasks through use of the gskkyman utility program. If necessary this PROFILE EXEC can be customized to meet local system requirements or account for use of Byte File System (BFS) directories other than the IBM® system deliverable defaults.

2. Invoke the gskkyman utility. After the top-level menu is displayed, select the Create new database function and provide appropriate data and responses to the prompts that are presented. As part of this task, specify the database name default (Database.kdb) and a database password that conforms to the guidelines established for your installation.
   Note:

   • Passwords associated with the key database and certificates are case sensitive. Be certain the password is entered as desired and is one that can adequately be recalled.
   • When a null response is provided during interaction with the gskkyman utility, enter must be used twice.

          Database Menu                                                    
                                                                           
      1 - Create new database                                              
      2 - Open database                                                    
      3 - Change database password                                         
      4 - Change database record length                                    
      5 - Delete database                                                  
      6 - Create key parameter file
      7 - Display certificate file (Binary or Base64 ASN.1 DER)
                                                                     
      0 - Exit program 
   
   Enter option number:
   1 <enter>
   
   Enter key database name (press ENTER to return to menu):
   Database.kdb <enter>
   Enter database password (press ENTER to return to menu):
   <enter password>
   Re-enter database password:
   <enter password>
   
   Enter password expiration in days (press ENTER for no expiration):
   35 <enter>
   
   Enter database record length (press ENTER to use 5000):
   <enter>
   <enter>
   
   Enter 1 for FIPS mode database or 0 to continue:
   0 <enter>
   
   Key database /etc/gskadm/Database.kdb created.
   
   Press ENTER to continue. 
   <enter>
   <enter>

3. Store the database password (in a predefined password stash file) to allow for use of key database by the SSL server.

          Key Management Menu 
            
          Database: /etc/gskadm/Database.kdb 
          Expiration: None
            
      1 - Manage keys and certificates 
      2 - Manage certificates  
      3 - Manage certificate requests 
      4 - Create new certificate request
      5 - Receive requested certificate or a renewal certificate 
      6 - Create a self-signed certificate 
      7 - Import a certificate 
      8 - Import a certificate and a private key 
      9 - Show the default key 
     10 - Store database password 
     11 - Show database record length 
            
      0 - Exit program 
            
   Enter option number (press ENTER to return to previous menu): 
   10 <enter>
   
   Database password stored in /etc/gskadm/Database.sth.  
   
   Press ENTER to continue.
   <enter>
   <enter>        

4. Exit the gskkyman program.

          Key Management Menu 
            
          Database: /etc/gskadm/Database.kdb 
          Expiration: None
            
      1 - Manage keys and certificates 
      2 - Manage certificates  
      3 - Manage certificate requests 
      4 - Create new certificate request
      5 - Receive requested certificate or a renewal certificate 
      6 - Create a self-signed certificate 
      7 - Import a certificate 
      8 - Import a certificate and a private key 
      9 - Show the default key 
     10 - Store database password 
     11 - Show database record length 
            
      0 - Exit program 
            
   Enter option number (press ENTER to return to previous menu): 
   0 <enter>        

5. Issue the OPENVM commands that follows to confirm that the necessary database files have been created, and to list the permissions of these files.
   • openvm list /etc/gskadm/

     Directory = '/etc/gskadm/'    
     Update-Dt  Update-Tm Type  Links          Bytes Path name component   
     09/12/2008 18:50:47   F        1          65080 'Database.kdb'  
     09/12/2008 18:51:21   F        1             80 'Database.rdb'  
     09/12/2008 18:51:01   F        1            129 'Database.sth'  
     Ready; T=0.01/0.01 18:51:34 

   • openvm list /etc/gskadm/ (own

     Directory = '/etc/gskadm/'  
     User ID    Group Name  Permissions Type  Path name component  
     gskadmin   security    rw- --- ---  F    'Database.kdb'  
     gskadmin   security    rw- --- ---  F    'Database.rdb'  
     gskadmin   security    rw- --- ---  F    'Database.sth'  
     Ready; T=0.01/0.01 18:51:37 

6. Issue the OPENVM PERMIT commands that follow to allow the SSL server to access the newly-created key database:
   • openvm permit /etc/gskadm/Database.kdb rw- r-- ---
   • openvm permit /etc/gskadm/Database.sth rw- r-- ---
7. Issue the OPENVM LIST command that follows to confirm that r (read) has been added to the group permissions for the key database and password stash files:
   • openvm list /etc/gskadm/ (own

     Directory = '/etc/gskadm/'  
     User ID    Group Name  Permissions Type  Path name component 
     gskadmin   security    rw- r-- ---  F    'Database.kdb'  
     gskadmin   security    rw- --- ---  F    'Database.rdb'  
     gskadmin   security    rw- r-- ---  F    'Database.sth'  
     Ready; T=0.01/0.01 18:55:15  

With the key database now in place, the SSL server can be initialized to confirm it has access to this database.

The PKCS #12 file could be created through the Key Management menu of the gskkyman utility and is placed in the BFS directory, it will be introduced below. Besides, a password file which has a file extension of .p12pw needs to be created to store the password of the PKCS #12 file and is placed in the same BFS directory. OPENVM PERMIT command should be used to grant read access to them to allow the SSL server to access them.

Note that the z/VM® system deliverable defines the GSKADMIN user ID as a class G user, so it does not have authorization to XAUTOLOG the SSL server. One can use the TCPMAINT user ID for this purpose, or manually logon the SSL server to verify the key database is accessible.

The key database now can be populated with the appropriate server and CA certificates required to provide SSL-protected communications for your installation. For more information about this task, see z/VM: TCP/IP User's Guide, SSL Certificate Management, under the subheading Key Management Menu.

To create a self-signed certificate for basic testing, follow the instructions provided under the subheading Create a Self-Signed Server or Client Certificate. The resulting self-signed certificate can be treated as though it was signed by an internal CA and exported to other SSL servers and client applications.

  1 - Manage keys and certificates 
  7 - Export certificate and key to a file 
  3 - Binary PKCS #12 Version 3       

  ...  
  Enter export file name (press ENTER to return to menu): 
  yourcert.arm <enter> 

  Enter export file password (press ENTER to return to menu): 
  <enter password> 
  Re-enter export file password: 
  <enter password> 

  Enter 1 for strong encryption, 0 for export encryption: 
  1 <enter> 
  ...        

When certificates are exported from the key database to a BFS file using a binary file format, via either of these gskkyman export options:

1 - Binary PKCS #12 Version 1
3 - Binary PKCS #12 Version 3

the resulting file, when propagated to a minidisk, should be processed with the OPENVM GETBFS command with the (BFSLINE NONE option to maintain the binary nature of the file.

Conversely, when certificates are exported from the key database to a BFS file using a Base64 file format, via either of these gskkyman export options:

2 - Base64 PKCS #12 Version 1
4 - Base64 PKCS #12 Version 3

the resulting file, when propagated to a minidisk, should be processed with the OPENVM GETBFS command with the (BFSLINE NL option to ensure the appropriate record structure is maintained.

To import a certificate with its private key into a new database, whether it is a certificate previously exported using gskkyman or an acquired certificate that has been placed into the /etc/gskadm BFS directory via an OPENVM PUTBFS command, one should access the gskkyman Key Management menu for the key database in use, and select the Import a certificate and a private key menu. From this menu, you are prompted to enter the name of the certificate file. The subject file should be in the /etc/gskadmin BFS directory and must be in PKCS #12 file format (usually, with a filename that ends with the string .p12).

Specify a unique label that conforms to the requirements for a z/VM certificate label when the certificate is imported into the key database. The label then can be specified as SSL configuration changes are implemented for your z/VM system.