Defining a security environment and certificates

Defining a security environment and certificates

Overview

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.

RACDCERT

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.

RACF prerequisites

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.

Example of using RACDCERT command

+---------------------------------------------------------------------+
|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 communication ID

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.

Defining default user for RACF

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:

  1. Create a FACILITY class profile called BPX.DEFAULT.USER with universal access READ and APPLDATA(defaultuser/ defaultgroup).
  2. Define a RACF user profile containing an OMVS segment for defaultuser.
  3. Define a RACF group profile containing an OMVS segment for defaultgroup.

Creating the CA certificate

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:

  • GENCERT creates a digital certificate and potentially a public or private key pair.
  • CERTAUTH relates to the certificate of a certificate authority (CA).
  • SUBJECTSDN specifies the subject's distinguished name. In the example, the following values are used:

    CN (common name) : BETA-CA-ZOS
    O (organization): BETA
    C (country) : DE

  • WITHLABEL specifies the label assigned to this certificate. If specified, this must be unique to the user ID with which the certificate is associated.

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.

Make the CA certificate HIGHTRUST

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.

Create the key ring

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.

Connect certificate to key ring

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:

  • ID(userid) indicates that the certificate being added to the key ring is a user certificate and user ID is the user ID associated with this certificate. If the ID keyword is not specified, it defaults to the value specified or the default value on the RACDCERT command.
  • CONNECT specifies that a digital certificate is being added to a key ring.
  • CERTAUTH indicates that the certificate being added to the key ring is a CA certificate.
  • USAGE allows the altering of the trust policy within the confines of a specific key ring. For example, a CERTAUTH certificate connected with USAGE(PERSONAL) can be used to demote a certificate-authority certificate so as to ensure that it is not used as a certificate authority in this key ring. It can be used as a user certificate if a private key is present. Typically, however, one is not present. Consequently, connecting a CERTAUTH certificate as USAGE(PERSONAL) is a way to mark it as NOTRUST for only this key ring. Also, a user certificate connected with USAGE(CERTAUTH) can be used to promote an ordinary user certificate to a CA certificate. It can then be used to authenticate user certificates for only this key ring.
  • DEFAULT specifies that the certificate is the default certificate for the ring. Only one certificate within the key ring can be the default certificate. If a default certificate already exists, its DEFAULT status is removed, and the new certificate in question becomes the default certificate. If you want the specified certificate to be the default, DEFAULT must be explicitly indicated.

Other certificates

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.

Create the BSA CI certificate

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:

  • SIGNWITH(CERTAUTH(LABEL('labelname')) specifies the certificate with a private key signing the certificate. The example above shows our CA certificate. If SIGNWITH is not specified, the default is to sign the certificate with the private key of the certificate that is being generated.
  • COMSVR stands for the BSA CI.

Connect COMSVR to key ring

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.

Enable COMUID to act as CA

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)

Refresh the RACLIST class

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

HostIdMapping certificates

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 profile in 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 to STC user

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)

Activate and raclist class SERVAUTH

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.