Importing a certificate from a file as a trusted CA certificate

If you are using a certificate authority for generating your certificates that are not one of the default certificate authorities for which certificates are already stored in the key database, or if you are using a z/OS® PKCS #11 token for which no default certificates exist, then you must import the certificate authority's certificate into your key database file or z/OS PKCS #11 token before you use the System SSL APIs. If you are using client authentication, then the CA certificate must be imported into the key database or z/OS PKCS #11 token of the server program. The client program's key database file or z/OS PKCS #11 token must have the CA certificate that is imported regardless of whether the SSL connection uses client authentication.

If you are using a self-signed certificate as the SSL server program's certificate and your SSL client program is also using the System SSL APIs, then you must import the server's self-signed certificate without its private key into the client program's key database file or z/OS PKCS #11 token.

If you are using a self-signed certificate as the SSL client program's certificate and your SSL server program is also using the System SSL APIs with client authentication requested, then you must import the client's self-signed certificate without its private key into the server program's key database file or z/OS PKCS #11 token.

If the CA certificate that is being imported was signed by another CA certificate, the complete chain must be present in the key database file or z/OS PKCS #11 token before the import. If the CA certificates chain consists of more than one certificate and the certificates exist in individual files, you must import the certificates starting with the root CA certificate.

If you are using a key database file, a number of well-known certificate authority (CA) certificates are stored in the key database when the key database is created. To get a certificate list, select 2 - Manage certificates from the Key Management Menu. The following figures contain lists of CAs for which certificates are stored on key database creation:

Figure 1. Certificate List (part 1)

                                                                      
       Certificate List                                               
                                                                      
       Database: /home/sufwl1/ssl_cmd/mykey.kdb
                                                                            
   1 - VeriSign Class 1 Public Primary CA                             
   2 - VeriSign Class 2 Public Primary CA                             
   3 - VeriSign Class 3 Public Primary CA                             
   4 - Thawte Server CA                                               
   5 - Thawte Premium Server CA                                       
   6 - Thawte Personal Basic CA                                       
   7 - Thawte Personal Freemail CA                                    
   8 - Thawte Personal Premium CA                                     
   9 - Equifax Secure Certificate Authority
                                                                      
   0 - Return to selection menu                                       
                                                                      
Enter label number (ENTER for more labels, p for previous list):      
 ===>

Figure 2. Certificate List (part 2)

                                                                               
       Certificate List                                                        
                                                                               
       Database: /home/sufwl1/ssl_cmd/mykey.kdb
   
   1 - Equifax Secure eBusiness CA-1       
   2 - Equifax Secure eBusiness CA-2       
   3 - Equifax Secure Global eBusiness CA-1     
   4 - VeriSign Class 1 Public Primary CA - G2
   5 - VeriSign Class 2 Public Primary CA - G2
   6 - VeriSign Class 3 Public Primary CA - G2
   7 - VeriSign Class 4 Public Primary CA - G2
   8 - VeriSign Class 1 Public Primary CA - G3
   9 - VeriSign Class 2 Public Primary CA - G3
                                                                           
   0 - Return to selection menu                                                
                                                                               
Enter label number (ENTER to return to selection menu, p for previous list):   
 ===>

Figure 3. Certificate List (part 3)

                                                                               
       Certificate List                                                        
                                                                               
       Database: /home/sufwl1/ssl_cmd/mykey.kdb

   1 - VeriSign Class 3 Public Primary CA - G3
   2 - VeriSign Class 4 Public Primary CA - G3
   3 - VeriSign Class 3 Public Primary CA - G5
                                                                              
   0 - Return to selection menu                                                
                                                                               
Enter label number (ENTER to return to selection menu, p for previous list):   
 ===>

To import a certificate without a private key into your key database file or z/OS PKCS #11 token, first get the certificate in a file with the file in either Base64-encoded, Binary encoded or PKCS #7 format. From the Key Management Menu or the Token Management Menu enter 7 to import a certificate:

Figure 4. Key Management Menu

                                                                 
       Key Management Menu                                       
                                                                 
       Database: /home/sufwl1/ssl_cmd/mykey.kdb
       Expiration Date: 2025/12/02  10:11:12    
                                                                 
   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): 7 <enter>                
Enter import file name (press ENTER to return to menu): cert.arm <enter>                 
Enter label (press ENTER to return to menu): cacert2 <enter>                           
                                                                                
Certificate imported.                                                           
                                                                                
Press ENTER to continue.                                                        
====>

Figure 5. Token Management Menu

                                                                 
       Token Management Menu                                     
                                                                 
       Token: TOKENABC                                           

     Manufacturer: z/OS PKCS11 API
     Model: HCR77A0
     Flags: x00000509 (INITIALIZED, PROT AUTH PATH, USER PIN INIT, RNG) 

   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 - Delete Token                                                  
                                                                                  
   0 - Exit program                                                             
                                                                                
Enter option number (press ENTER to return to previous menu): 7 <enter>                
Enter import file name (press ENTER to return to menu): cert.arm <enter>                 
Enter label (press ENTER to return to menu): cacert2 <enter>                           
                                                                                
Certificate imported.                                                           
                                                                                
Press ENTER to continue.                                                        
====>

You are prompted to enter the certificate file name and your choice of a unique label that are assigned to the certificate.

When the certificate is imported, you receive a message that indicates the import was successful. The certificate is treated as "trusted" so that it can be used in verifying incoming certificates. For a program that is acting as an SSL server, this certificate is used during the verification of a client's certificate. For a program that is acting as an SSL client, this certificate is used to verify the server's certificate that is sent to the client during SSL handshake processing.