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.
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.
DFH$RING is in library .SDFHSAMP.
Edit the values in DFH$RING to create a suitable key ring and certificates:
- 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 (768 )"
These
values define appropriate fields in the distinguished names of the
generated certificates. 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 '.SDFHSAMP(DFH$RING)' 'firstname lastname webservername [ FORUSER(userid) ] '
where userid is
the CICS region user ID.
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.
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-EJB-Container
- This certificate can be used in the CERTIFICATE attribute of a
CORBASERVER definition.
- 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-Default-Certificate
- This certificate is marked as the default certificate for the
key ring and is the one that is used for all TCPIPSERVICEs and CORBASERVERs
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).
You can create and add further certificates to the key ring.