The examples in this section show how to use the RACDCERT command to define the SSL security environment for the BSA CI, and how to specify that you are working with certificates.
The RACDCERT command is the primary administrative tool for managing digital certificates using RACF.
The RACDCERT command is used to manage resources in the following classes:
DIGTCERT
Profiles in the class DIGTCERT contain information on digital certificates as well as the certificate itself. The user ID associated with the certificate can be found in the APPLDATA field of the profile.
DIGTRING
Profiles in the class DIGTRING contain information on key rings and on certificates that are part of each key ring. Key rings are named collections of the personal certificates, site certificates, and CA certificates associated with a specific user.
DIGTNMAP
Profiles in class DIGTNMAP contain information on certificate name filters.
Profiles in the classes DIGTCERT, DIGTRING and DIGTNMAP are automatically maintained through RACDCERT command processing. You cannot administer profiles in these classes using the RDEFINE, RALTER, and RDELETE commands.
Make sure that the DIGTCERT and DIGTRING classes are active before defining certificates or key rings to RACF. If necessary, activate these classes:
SETROPTS CLASSACT(DIGTCERT DIGTRING)
Be sure to perform a refresh after each update or change:
SETROPTS RACLIST (DIGTRING DIGTCERT) REFRESH
Also ensure that the RACDCERT command is defined as an authorized TSO command in the IKJTSOxx member.
In order to issue the RACDCERT command, you must have access to the FACILITY class IRR.DIGTCERT function with UPDATE or CONTROL access.
+---------------------------------------------------------------------+
|jobcard |
|//RACFDEF EXEC PGM=IKJEFT1A,DYNAMNBR=nn |
|//SYSTSPRT DD SYSOUT=* |
|//SYSLBC DD DISP=SHR,DSN=SYS1.BRODCAST |
|//SYSUADS DD DISP=SHR,DSN=SYS1.UADS |
|//SYSPRINT DD SYSOUT=* |
|//SYSTSIN DD * |
| RACDCERT.... |
|/* |
+---------------------------------------------------------------------+
Define a user ID (for example, COMUID) and associate it with the BSA CI started task.
The user ID must have its own OMVS segments or use the default OMVS segment. It will need READ access to the facility class BPX.DEFAULT.USER.
To set up RACF so that it automatically uses default OMVS segments for users and groups that do not have their own OMVS segments in their USER or GROUP profiles, proceed as follows:
Create the certificate authority (CA) certificate.
The following is an example of the command used to create this most important certificate:
RACDCERT GENCERT CERTAUTH +
SUBJECTSDN(CN('BETA-CA-ZOS') +
O('BETA') C('DE')) *
WITHLABEL('BSA-ZOS-CA')
where:
CN (common name) : BETA-CA-ZOS
O (organization): BETA
C (country) : DE
Note: The label name is stripped of leading and trailing blanks. If a single quotation mark is intended to be part of the label name, you must use two single quotation marks together for each single quotation mark within the string, and the entire string must then be enclosed within single quotation marks.
The sub-keywords TRUST | NOTRUST | HIGHTRUST indicate whether the status of the certificate is trusted, not trusted, or highly trusted. Whether the certificate is not trusted or trusted depends on whether or not the certificate is valid and whether the private key has been compromised or not. Since highly trusted certificates are by definition trusted certificates, any certificate usage that was enabled by marking the certificate trusted will also be enabled by marking the certificate highly trusted. However, only CA certificates can be highly trusted. The keyword ALTER is used to change the status to HIGHTRUST, for example:
RACDCERT CERTAUTH ALTER(LABEL('BSA-ZOS-CA')) HIGHTRUST
Note: The value of the LABEL keyword is case-sensitive.
The following is an example of how to use the RACDCERT command to create a key ring for the started task user ID running the BSA CI (in this example: COMUID):
RACDCERT ADDRING(BETA-RING) ID(COMUID)
where:
ADDRING creates a key ring. Only users can have a key ring. Key ring names become the names of RACF profiles in the DIGTRING class, and can contain only characters allowed in RACF profile names. Although asterisks are allowed in ring names, a single asterisk is not permitted.
Note: For a CA certificate, the user who owns the ring is the BSA CI. Lowercase characters are permitted. A key ring name can be up to 237 characters in length. Since only user IDs can have key rings, neither CERTAUTH nor SITE can be specified with ADDRING.
The following is an example of how to use RACDCERT to connect the certificate to the key ring:
RACDCERT ID(COMUID) +
CONNECT(CERTAUTH +
LABEL('BSA-ZOS-CA') +
RING(BETA-RING) +
USAGE(PERSONAL) +
DEFAULT)
where:
Once you have created a CA certificate, you can start issuing other types of certificates, for example, an SSL certificate for the BSA CI started task user ID (in this example: COMUID) needed to process handshakes with future client certificates belonging to external or internal users.
Use RACDCERT as in the following example to create the BSA CI certificate:
RACDCERT GENCERT ID(COMUID) +
SIGNWITH(CERTAUTH LABEL('BSA-ZOS-CA')) +
SUBJECTSDN(CN('betasystem.com') +
O('BETA') C('DE')) +
WITHLABEL('BSA_ZOS_COMSVR')
where:
Connect the BSA CI certificate to the key ring. For example:
RACDCERT ID(COMUID) CONNECT(ID(COMUID) +
LABEL('BSA_ZOS_COMSVR') +
RING(BETA-RING))
Note: We did not specify USAGE because the default value of USAGE is the same as in the certificate added, i.e. we have kept USAGE(CERTAUTH). We also omitted DEFAULT as we chose not to make the CA certificate the DEFAULT in this key ring.
The following commands allow the BSA CI user ID to act as a CA, for example:
PE IRR.DIGTCERT.GENCERT CL(FACILITY) ID(COMUID) +
ACC(CONTROL)
PE IRR.DIGTCERT.LIST CL(FACILITY) ID(COMUID) ACC(R)
PE IRR.DIGTCERT.LISTRING CL(FACILITY) ID(COMUID) +
ACC(R)
Perform a refresh for the RACLIST class, For example:
SETROPTS GENERIC (FACILITY) REFRESH
SETROPTS RACLIST (FACILITY) REFRESH
SETROPTS GENERIC(DIGTRING DIGTCERT) REFRESH
SETROPTS RACLIST (DIGTRING DIGTCERT) REFRESH
You can add a HostIdMapping extension to certificates you create for certain users, thus enabling you to specify the user IDs for logging onto particular servers (or hosts).
The HostIDMapping extension (OID 1 3 18 0 2 18 1) is an IBM extension that is also available for public use. RACF automatically maps a valid certificate to the RACF user ID provided in the extension.
Controlling an identity used for logon purposes is an essential security objective. Therefore, you must enable the BSA CI to accept logons from clients who have been issued certificates with HostIdMapping extensions by creating profiles in the RACF class SERVAUTH.
Define a profile in class SERVAUTH for each server (host) name you want your BSA CI to honor when accepting logons for certificates containing HostIdMapping extensions. The profile has the format IRR.HOST.hostname, where the value of hostname is usually a domain name, such as betasystems.com. This domain name must be entered in the entry for HostIdMap in the certificate extension but without the subject ID portion in the APPL section, for example:
RDEF SERVAUTH IRR.HOST.BETASYSTEMS.COM UACC(NONE)
Note: Ensure that your CA certificate is defined as HIGHTRUST. See "Make the CA certificate HIGHTRUST".
Give READ rights to the BSA CI started task user ID (in this example: COMUID):
PE IRR.HOST.BETASYSTEMS.COM CL(SERVAUTH) ID(COMUID) +
ACC(R)
Now activate and raclist class SERVAUTH, for example:
SETR CLASSACT(SERVAUTH)
SETR RACLIST(SERVAUTH)
SETR RACLIST(SETRAUTH) REFR
Note: On a z/OS system, HostIdMapping is not honored if the target user ID is created after the start of the validity period for the certificate containing the HostIdMappings extension. Therefore, if you are creating user IDs specifically for certificates with HostIdMappings extensions, make sure that you create the user IDs before the certificate requests are submitted.