Generating a keyring

Generating a keyring and certificate for secure connections

If you wish to connect to the C\Prof Web UI application server securely using HTTPS, you will need to generate a keyring containing a digital certificate. A digital certificate is an electronic document issued by a certificate authority (CA) that is used to identify the server and provides the basis for secure connections. In the case of the C\Prof Web UI, you will need to create a keyring and certificate for the user ID being used to run the application server.

Before you begin

Before you begin, read the following important information:

• The specific procedure required for generating a keyring and digital certificate will vary depending on your site security policies, company naming conventions, and your mainframe security product. As such any security procedures must be conducted by an appropriately authorized site security administrator who can make adjustments as required.

• A certificate authority (CA) is an entity that issues digital certificates. The procedure below includes steps for creating your own certificate authority. However, if you already have a certificate authority that you would like to use, simply skip this step and substitute your own certificate authority in the remaining steps.

Procedure using IBM RACF

The following procedure demonstrates a basic method for creating a certificate authority (CA), a keyring, and a digital certificate using IBM RACF. For more information on RACF and security with certificates, refer to the topic RACF and digital certificates in the z/OS User's Guide in the IBM Knowledge Center.

You can execute the following commands via ISPF Primary Option Menu 6 Command, directly in TSO/E, or by creating your own batch job. When inserting these commands into a batch job, be sure to add line continuation characters (+) to each new line as required.

"Note: Be sure to issue the SETROPTS commands described throughout this procedure to activate the sharing of in-storage profiles."

1. Allow the user ID that will run the C\Prof Apache Tomcat web server to read keyrings. A keyring is used to hold digital certificates. To allow access, submit the following PERMIT commands, substituting <USERID> with the user ID of your choice:

   PERMIT IRR.DIGTCERT.LIST CLASS(FACILITY) ID(<USERID>) ACC(READ)
   
   PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(<USERID>) ACC(READ)
   
   SETROPTS RACLIST(FACILITY) REFRESH
   

2. If your organization does not have a certificate authority (CA) (or you do not wish to use it), you can generate and activate your own CA for use by the C\Prof application server. To do this, submit the following RACDCERT GENCERT command, selecting an appropriate CA expiration date value for DATE as required.

   If you have a SAF prefix you would like to use for C\Prof, consider using this value in the OU (organizational unit) parameter as a means of identification. Otherwise, you may use the value supplied below.

   The name of the CA resulting from this step is CProfCA:

   RACDCERT CERTAUTH GENCERT
     SUBJECTSDN(CN('CPROF CertAuth for security domain')
     OU('TXCSRVR')) WITHLABEL('CProfCA') TRUST NOTAFTER(DATE(2024/12/31))
   
   SETROPTS RACLIST(DIGTCERT, DIGTRING) REFRESH
   

3. Create an empty keyring for the user ID of the C\Prof Apache Tomcat web server. To do this, submit the following RACDCERT ADDRING command, substituting <USERID> with the user ID you specified in step 1.

   The name of the keyring resulting from this step is CProfKeyring.TXCSRVR:

   RACDCERT ADDRING(CProfKeyring.TXCSRVR) ID(<USERID>)
   
   SETROPTS RACLIST(DIGTCERT,DIGTRING) REFRESH
   

4. Generate a digital certificate for the C\Prof Apache Tomcat web server. To do this, submit the following RACDCERT GENCERT command with these substitutions:

   • Replace <USERID> with the user ID you specified in step 1.
   • Replace the two instances of <HOST> with the hostname of the mainframe you will use to serve the C\Prof Web UI. The hostname must match the name you will eventually specify in your web browser to log on to the Web UI.
   • If you have a SAF prefix you would like to use for C\Prof, consider using this value in the OU (organizational unit) parameter as a means of identification. Otherwise, you may use the value supplied below.
   • Replace <COMPANY> with the name of your organization.
   • If you did not complete step 2 and therefore did not create a new certificate authority, replace CProfCA with the name of your own CA.
   • Replace the certificate expiration date in DATE as required.

   RACDCERT ID (<USERID>) GENCERT SUBJECTSDN(CN('<HOST>') O('<COMPANY>') OU('TXCSRVR'))
     WITHLABEL('DefaultCProfServer.TXCSRVR') SIGNWITH(CERTAUTH LABEL('CProfCA'))
     NOTAFTER(DATE(2024/12/31)) ALTNAME(DOMAIN('<HOST>'))
   
   SETROPTS RACLIST(DIGTCERT,DIGTRING) REFRESH
   

5. Connect the digital certificate to the C\Prof Apache Tomcat web server keyring. To do this, submit the following RACDCERT CONNECT command, substituting <USERID> with the user ID you specified in step 1:

   RACDCERT ID(<USERID>) CONNECT(LABEL('DefaultCProfServer.TXCSRVR')
     RING(CProfKeyring.TXCSRVR) DEFAULT)
   

6. Connect the certificate authority to the C\Prof Apache Tomcat web server keyring. To do this, submit the RACDCERT CONNECT command, substituting <USERID> with the user ID you specified in step 1. If you did not complete step 2 and therefore did not create a new certificate authority, replace CProfCA with the name of your own CA:

   RACDCERT ID(<USERID>) CONNECT (RING(CProfKeyring.TXCSRVR)
     LABEL('CProfCA') CERTAUTH)
   
   SETROPTS RACLIST(DIGTCERT,DIGTRING) REFRESH
   

To import the certificate into your web browser:

1. Export the digital certificate from RACF into a data set. To do this, submit the RACDCERT EXPORT command, replacing <USERID> with the user ID you specified in step 1. If you did not complete step 2 and therefore did not create a new certificate authority, replace CProfCA with the name of your own CA. The result is a certificate file named <USERID>.CPROF.TXCSRVR.CER:

   RACDCERT CERTAUTH EXPORT(LABEL('CProfCA'))
      DSN('<USERID>.CPROF.TXCSRVR.CER')
   

2. Copy the exported certificate <USERID>.CPROF.TXCSRVR.CER from the mainframe to your PC. The simplest method for achieving this is by creating a new, empty file on your PC and then manually copying and pasting the contents of <USERID>.CPROF.TXCSRVR.CER into this new file. If you wish to use FTP instead, be sure to use ASCII transfer mode.

3. Import the exported digital certificate into your web browser. Refer to the help topics for your web browser for more information. If you are using Google Chrome, instruction can be found in Importing a digital certificate.

What to do next

If you have not already done so, install the C\Prof Web UI configured for HTTPS. For more information, see Step 10: Install the C\Prof Web UI (web server and application).

Tip: If you have already installed the C\Prof Web UI, you can change from HTTP to HTTPS by adjusting the server configuration. For more information, see Web UI application server configuration.