Building a key ring with certificates using DFH$RING

DFH$RING is a sample REXX program that builds a key ring, creates a signing certificate (certificate authority certificate), creates additional certificates, and adds the certificates to the key ring.

Before you begin

You must have the required authorization to run the RACF commands. Your user ID must have CONTROL access to create the signing certificate the first time your run the program. If you run the program again, you require only UPDATE access.

About this task

DFH$RING is in library CICSTS53.CICS.SDFHSAMP. Edit the values in DFH$RING to create a suitable key ring and certificates:

Procedure

Enter values for the firstname, lastname, and hostname variables.
The firstname and lastname values are concatenated together to form the name of the key ring. Enter the host name of your Web server for the hostname variable.
Optional: Enter a value for the FORUSER variable if you are building a key ring for a different user ID, such as a CICS region user ID.
If you have a signing certificate (certificate authority certificate), enter the label in the certifier variable.
If you do not have a signing certificate, replace the variables for the RACDCERT CERTAUTH GENCERT command with suitable values and RACF can create it for you:
```
"RACDCERT CERTAUTH GENCERT",
" SUBJECTSDN(CN('CICS Sample Certification Authority' ) ",
            "OU('"department"'                        ) ",
            "O ('"organization"'                      ) ",
            "L ('"city"'                              ) ",
            "SP('"state"'                             ) ",
            "C ('"country"'                           ))",
" NOTBEFORE(DATE("start")  TIME(00:00:00)              )",
" NOTAFTER (DATE("finish") TIME(23:59:59)              )",
" WITHLABEL("certifier"                                )",
" SIZE     (1024                                        )"
```
These values define appropriate fields in the distinguished names of the generated certificates. The country code for the country variable must be an ISO 3166-1 code. For a list of valid codes, see https://www.iso.org/iso-3166-country-codes.html. start and finish determine the validity of the certificate. certifier is the label of the self-signed Certificate Authority certificate that is used to sign the other certificates. The SIZE parameter specifies the size, in bits, of the private key that is associated with the certificate. The larger the size, the more secure the key. The most common size is 1024.
DFH$RING creates the signing certificate only if it does not already exist.
Edit the variables for the RADCERT GENCERT RACF commands to create appropriate certificates to add to your key ring.
DFH$RING has four examples that you can edit, add to, or remove. Ensure that the certifier variable on the SIGNWITH parameter matches the label of your signing certificate.
Edit the labels for the RACDCERT CONNECT RACF commands to match your certificates. Ensure that the signing certificate is added to the key ring first, because it signs all the other certificates.

Run DFH$RING to create the key ring and certificates as follows:

EXEC 'CICSTS53.CICS.SDFHSAMP(DFH$RING)' 'firstname lastname webservername  [ FORUSER(userid) ] '

where userid is the CICS region user ID.

Results

The DFH$RING program creates a key ring with name firstname.lastname which is owned by the userid user ID. Any existing key ring with that name is replaced. If you omit the FORUSER parameter, the key ring is owned by the user ID that you used to run the program. DFH$RING creates a signing certificate if required and adds it to the key ring, followed by the other certificates.

Example

If you run DFH$RING with the default values, DFH$RING creates certificates with the following labels:

lastname-Web-Server: This certificate can be used in the CERTIFICATE attribute of TCPIPSERVICEs with PROTOCOL(HTTP). The distinguished name within the certificate has a common name of webservername, which must be the same as the host name associated with the connection. Web browsers usually check that the common name in the certificate matches the host name of the server from which it is received.
lastname-IP-CONNECTION: This certificate can be used for IP interconnectivity (IPIC). It can be used in CERTIFICATE attributes of resource definitions that are required for a CICS region to use IPIC. This sample certificate is for a CICS region to use as a client certificate and as a server certificate during an SSL handshake that occurs when an IPCONN is acquired. It can be used in the CERTIFICATE attribute of an IPCONN definition for a client certificate and the CERTIFICATE attribute of a TCPIPSERVICE definition with PROTOCOL(IPIC) for a server certificate.
lastname-2048-Certificate: This certificate can be used for CICS® systems that require high-strength certificates. It can be used in CERTIFICATE attributes of TCPIPSERVICE, IPCONN, and URIMAP definitions, and EXEC CICS WEB OPEN commands.
lastname-Default-Certificate: This certificate is marked as the default certificate for the key ring and is the one that is used for all TCPIPSERVICE resources that do not specify a CERTIFICATE attribute. This certificate also contains a common name of webservername.
Verisign Class 1 Primary CA
Verisign Class 2 Primary CA
IBM World Registry CA: These certificates are required to validate client certificates that you might receive that have been signed by these Certificate Authorities. If you intend to accept client certificates signed by other Certificate Authorities, or certificates that you have created yourself, you will have to add their certificates to the key ring manually, using the RACDCERT CONNECT command. When you add a certificate to the key ring in this way, you must specify USAGE(PERSONAL).

What to do next

You can create and add further certificates to the key ring.