Chapter 2. RACF for PKI Services
2.4 Setting up the RACF environment for PKI Services
2.4.4 Using RACF to create certificates
The certificate authority, commonly known as CA, acts as a trusted party to ensure that users who engage in e-business can trust each other. A certificate authority vouches for the identity of each party through the certificates it issues. In addition to proving the identity of the user, each certificate includes a public key that enables the user to verify and encrypt communications.
You can use RACF to create, register, store, and administer digital certificates and their associated private keys, and to build certificate requests that can be sent to a certificate authority for signing. You can also use RACF to manage key rings of stored digital certificates. Digital certificates and key rings are managed in RACF primarily by using the RACDCERT command.
RACF enables you to manage three types of digital certificates:
User certificate A certificate that is associated with an RACF user ID and is used to authenticate the user’s identity
CA certificate A certificate that is associated with a certificate authority and is used to verify signatures in other certificates
Site certificate A certificate that is associated with a server or network entity other than a user or certificate authority
Your organization may already have rules for creating certificates. If not, such rules should be discussed and established. An essential part of any certificate is the
distinguished name
that consists of the components listed in Table 2-2.Table 2-2 Components of Distinguished Name
Common name (CN)*
Title (T)*
Organization Unit (OU)
Organization (O)
Locality (L)
Street (STREET)*
State/Province (SP)
Chapter 2. RACF for PKI Services 65
These abbreviations are used as subkeywords for defining certificates. The fields with * are not typical for CA certificates.
The RACDCERT command enables an RACF-defined user ID to use a digital certificate as identification. The certificate must be one of the supported formats contained in an MVS data set. For more information about these formats refer to
z/OS Security Server RACF Command Language Reference, SA22-7687.
RACDCERT is used to store and maintain digital certificates in RACF and should be used for all maintenance of the DIGTCERT class profiles and related USER profile fields. However, USER-related record type 0207 (User Certificate Name Record) provides user ID, certificate name, and certificate label. For more details see Chapter 10, “RACF Database Unload Utility(IRRDBU00)” in z/OS V1R4.0
Security Server RACF Macros and Interfaces, SA22-7682.
The RACDCERT command is your primary administrative tool for managing digital certificates using RACF. Granular authorities for use of the RACDCERT command by users not having SYSTEM SPECIAL are controlled through profiles in the FACILITY class of the type IRR.DIGTCERT.function. It is outside the scope of this book to show the best set of profiles, UACCs, and access lists for these profiles. One possible approach is suggested in 2.4.12, “Protect certificate functions” on page 79, as part of our CLIST to install PKI Services.
The RACDCERT command is used to manage resources in these classes:
DIGTCERT Profiles in the DIGTCERT class contain information about 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 DIGTRING class contain information about key rings and the certificates that are part of each key ring. Key rings are named collections of the personal, site, and CA certificates associated with a specific user.
DIGTNMAP Profiles in the DIGTNMAP class contain information about certificate name filters.
Postal Code (POSTALCODE)*
Country (C)
Note: The MAIL, POSTALCODE, and STREET components are valid for PKI
Services scripts only. They cannot be used as subkeywords in the RACDCERT command.
Profile names in the DIGCERT class are in the form:
serial-number.issuer’s-distinguished-name
For example:
41D87A3B05D(serial number)
OU=VeriSign Class1.O=VeriSign.L=Internet (issuer‘s distinguished name)
Any characters that would not be valid in a profile name, such as a blank, will be replaced with X’4A’ (¢). The profile name for this DIGTCERT profile would be:
41D87A3B05.OU=VeriSign¢Class1.O=VeriSign.L=Internet
Profile names in the DIGTRNG class are in the form:
owning-userid.key-ring-name
You may use the SEARCH command (SR) or the RLIST command to find all entries defined in the classes. For example:
SR CLASS(DIGTCERT), SR CLASS(DIGTRING) RLIST DIGTCERT * , RLIST DIGTRING * .
The output from RLIST has almost 40 times more lines due to the usual
information coming from RLIST, such as OWNER, UACC, date of creation, your access, access list (not applicable here), installation data, and application data.
Create the CA certificate
The command to create this most important certificate is shown in Example 2-15.
Example 2-15 Command to create the certificate authority certificate
RACDCERT GENCERT CERTAUTH SUBJECTSDN(OU('ITSO PSIE CA') + O('IBM') C('US')) WITHLABEL('IBM ITSO PSIE PKI1') + NOTAFTER(DATE(2020/01/01))
GENCERT Creates a digital certificate and, potentially, a public or private key pair.
Note: Profiles in the DIGTCERT, DIGTRING, and DIGTNMAP classes are
maintained automatically through RACDCERT command processing. You cannot administer profiles in these classes using the RDEFINE, RALTER, and RDELETE commands. These commands do not operate with profiles in the DIGTCERT, DIGTRING, and DIGTNMAP classes.
Chapter 2. RACF for PKI Services 67 CERTAUTH Relates to certificate of a Certificate Authority (CA)
SUBJECTSDN Specifies the subject’s distinguished name, which consists of the components in Table 2-2 on page 64. In our case, organization unit is OU=ITSO PSIE CA (ITSO Redbooks in Poughkeepsie, and this is our CA), organization is O=IBM, country is C=US.
WITHLABEL(‘label-name’)
Specifies the label assigned to this certificate. If specified, this must be unique to the user ID with which the
certificate is associated.
NOTAFTER Specifies the local date and time after which the
certificate is no longer valid.
Example 2-16 Job for RACDCERT
//your job card
//STEP1 EXEC PGM=IKJEFT01 //SYSLBS DD DSN=SYS1.BRODCAST,DISP=SHR //SYSTSPRT DD SYSOUT=* //SYSTSIN DD * RACDCERT GENCERT CERTAUTH SUBJECTSDN(OU('ITSO PSIE CA') +
O('IBM') C('US')) WITHLABEL('IBM ITSO PSIE PKI1') + NOTAFTER(DATE(2020/01/01))
Making the CA Certificate HIGHTRUST
The subkeywords 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 the certificate is valid and whether the private key has been compromised. Because highly trusted certificates are by definition trusted certificates, any certificate usage that was enabled by marking the certificate trusted is also enabled by marking the certificate highly trusted.
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. We associated this CA certificate with Web server PKI1.
Note: It is recommended that you set up a job to use the RACDCERT
command when a long string of keywords and their values is needed. (See Example 2-16.)
However, only CA certificates can be highly trusted. The keyword ALTER is used to change the status to HIGHTRUST:
RACDCERT CERTAUTH ALTER(LABEL(‘IBM ITSO POK PKI1’)) HIGHTRUST
Backup to a data set
It is absolutely critical to back up the certificate into a data set with the PKCS12DER format. The keyword for it is EXPORT:
RACDCERT CERTAUTH EXPORT(LABEL(‘IBM ITSO PSIE PKI1’)) + DSN(‘PKI.CAPKI1.BACKUP.P12BIN’) +
FORMAT(PKCS12DER) PASSWORD(‘xxxxxxx’)
Save the CA certificate to a data set for import to a UNIX file
The CA certificate should be placed into an MVS data set in the DER format and then copied to the HFS file. See Example 2-17 for details.
Example 2-17 Placing CA certificate into an MVS data set RACDCERT CERTAUTH EXPORT(LABEL(‘IBM ITSO POK PKI1’)) + DSN(‘PKI.CAPKI1.DERBIN’) FORMAT(CERTDER)
chown PKISTU /var/pkiserv
oput 'pki.capki1.derbin' '/var/pkiserv/pkiserv1/cacert.der' binary chmod 755 /var/pkiserv/cacert.der
chown pkistu /var/pkiserv/*
Create PKI Services key ring
The RACDCERT command to create a key ring for the CA certificate is:
RACDCERT ADDRING(CARING) ID(PKISTU),
ADDRING(ring name) This creates a key ring. Only users can have a key ring.
Key ring names become names of RACF profiles in the DIGTRING class and can contain only characters that are allowed in RACF profile names. Although asterisks are allowed in ring names, a single asterisk is not allowed. For a CA certificate, the user who owns the ring is the PKI daemon. Lowercase characters are permitted. A key ring
Note: The value of the LABEL keyword is case-sensitive. (Ours is in
uppercase.)
Note: Be careful when you issue this command because the password is
unencrypted, so you have to remember or find a secure place to store the password for future use. If the password is lost, this backup becomes useless. Also the password value is case-sensitive.
Chapter 2. RACF for PKI Services 69
name can be up to 237 characters in length. Because only user IDs can have key rings, neither CERTAUTH nor SITE can be specified with ADDRING.
After creating the key ring, the certificate should be added to the key ring. The command is:
RACDCERT ID(PKISTU)
CONNECT(CERTAUTH LABEL(‘IBM ITSO PSIE PKI1’) + RING(CARING) USAGE(PERSONAL) DEFAULT),
ID(userid) Indicates that the certificate being added to the key ring is a user certificate, and userid is the user ID that is 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 in order to ensure that it is not used as a certificate authority in this ring. It can be used as a user certificate if a private key is present. Typically, one would not be present. Consequently, connecting a CERTAUTH certificate as USAGE(PERSONAL) is a way of marking it NOTRUST for this key ring only. 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 this key ring only.
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 specified certificate becomes the default certificate. If you want the specified certificate to be the default, DEFAULT must be explicitly specified.
Note: All subkeywords belong to CONNECT. (For example, in the RACDCERT
command, the left bracket is immediately after CONNECT and the right bracket is after DEFAULT.)
Create the Web server SSL certificate
After we create our CA certificate, we can start issuing other types of certificates, such as an SSL certificate for our Web server started task user ID that is needed to process handshakes with upcoming client certificates belonging to external or internal users.
The command to achieve this is shown in Example 2-18.
Example 2-18 Command to issue the certificate
RACDCERT GENCERT ID(WEBSTU) +
SIGNWITH(CERTAUTH LABEL(‘IBM ITSO PSIE PKI1’)) + SUBJECTSDN(CN('wtsc64oe.itso.ibm.com’) +
O('IBM') L(‘POUGHKEEPSIE’) SP(‘NEW YORK) C('US')) WITHLABEL('SSL PKI1’) + NOTAFTER(DATE(2020/01/01))
SIGNWITH(CERTAUTH(LABEL(‘label-name’))
Specifies the certificate with a private key that is signing the certificate. In our case it is 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.
Create the Web server key ring
Similar to the CA, we have to create a key ring for the certificates of our Web server with the command:
RACDCERT ADDRING(SSLRING) ID(WEBSTU)
We now connect the CA certificate to the ring belonging to the Web server:
RACDCERT ID(WEBSTU) CONNECT(CERTAUTH LABEL(‘IBM ITSO PSIE PKI1’) + RING(SSLRING))
We connect the Web server certificate to the Web server ring with this command:
RACDCERT ID(WEBSTU) CONNECT(ID(WEBSTU) LABEL(‘SSL PKI1’) RING(SSLRING) + USAGE(PERSONAL) DEFAULT)
LIST certificates
Now we see what information we get when displaying our certificates.
Note: We did not specify USAGE because the default value of USAGE is the
same as in the added certificate; That is, we preserved USAGE(CERTAUTH). We also omitted DEFAULT, because we did not want to make the CA
Chapter 2. RACF for PKI Services 71
LIST the CA certificate
RACDCERT CERTAUTH LIST(LABEL('IBM ITSO PSIE PKI1'))
The output of the command is shown in Table 2-19.
Example 2-19 Listing the CA certificate
Digital certificate information for CERTAUTH: Label: IBM ITSO PSIE PKI1 Certificate ID: 2QiJmZmDhZmjgcnC1EDJ4+LWQNfiycVA19LJ8UBA Status: HIGHTRUST Start Date: 2003/04/30 00:00:00 End Date: 2020/01/01 23:59:59 Serial Number: >00< Issuer's Name: >OU=ITSO PSIE CA.O=IBM.C=US< Subject's Name: >OU=ITSO PSIE CA.O=IBM.C=US< Key Usage: CERTSIGN Private Key Type: ICSF Private Key Size: 1024 Ring Associations: Ring Owner: PKISTU Ring: >CARING< Ring Owner: WEBSTU Ring: >SSLRING<
Now we RLIST our CA certificate:
RL DIGTCERT 00.OU=ITSO¢PSIE¢CA.O=IBM.C=US ALL
The output is shown in Example 2-20.
Example 2-20 RLIST of our certificate
CLASS NAME --- ---- DIGTCERT 00.OU=ITSO¢PSIE¢CA.O=IBM.C=US LEVEL OWNER UNIVERSAL ACCESS YOUR ACCESS WARNING
Note: The keyword CERTAUTH must be used when listing a CA certificate.
The value of LABEL is case sensitive, so type IBM and not ibm. Also, CERTAUTH may be placed after list(label( ’ ‘))
--- --- --- --- --- 00 ANTOFF ALTER ALTER NO INSTALLATION DATA --- NONE APPLICATION DATA --- irrcerta SECLEVEL --- NO SECLEVEL CATEGORIES --- NO CATEGORIES SECLABEL --- NO SECLABEL AUDITING --- FAILURES(READ) GLOBALAUDIT --- NONE NOTIFY --- NO USER TO BE NOTIFIED
CREATION DATE LAST REFERENCE DATE LAST CHANGE DATE (DAY) (YEAR) (DAY) (YEAR) (DAY) (YEAR) --- --- --- 120 03 120 03 120 03 ALTER COUNT CONTROL COUNT UPDATE COUNT READ COUNT --- --- --- --- 000000 000000 000000 000000 USER ACCESS ACCESS COUNT ---- --- --- --- NO USERS IN ACCESS LIST ID ACCESS ACCESS COUNT CLASS ENTITY NAME --- --- --- --- ---
Chapter 2. RACF for PKI Services 73
NO ENTRIES IN CONDITIONAL ACCESS LIST
LIST the Web server (SSL) certificate
The command to display the Web server certificate is:
RACDCERT ID(WEBSTU) LIST(LABEL('SSL PKI1'))
The output from this command is shown in Table 2-21.
Example 2-21 Listing certificate for Web server
Digital certificate information for user WEBSTU: Label: SSL PKI1 Certificate ID: 2QbmxcLi4+Ti4tNA19LJ8UBA Status: TRUST Start Date: 2003/04/30 00:00:00 End Date: 2020/01/01 23:59:59 Serial Number: >00< Issuer's Name: >OU=ITSO PSIE CA.O=IBM.C=US< Subject's Name: >CN=wtsc64oe.itso.ibm.com.O=IBM.L=POUGHKEEPSIE.SP=NEW YORK.C=US< Private Key Type: Non-ICSF Private Key Size: 1024 Ring Associations: Ring Owner: WEBSTU Ring: >SSLRING<
Now, we list our Web server certificate issued by our CA:
RL DIGTCERT 01.OU=ITSO¢PSIE¢CA.O=IBM.C=US ALL
Part of the output is shown in Example 2-22 on page 74.
Note: The value of the UACC denotes the status of the certificate: ALTER if
the certificate is TRUSTed or HIGHTRUSTed. The APPLDATA field contains the user ID associated with the certificate. (In our CA certificate, it is the IBM-supplied user ID irrcerta. User ID irrcerta will be always in APPLDATA for NOTRUSTed certificates.
Note: The keyword ID( ) must be used when listing a user certificate. Also,
ID( ) may be placed after list(label( ’ ‘)). Remember that the value of LABEL is case sensitive.
Example 2-22 RLIST of the Web server certificate
CLASS NAME --- ---- DIGTCERT 01.OU=ITSO¢PSIE¢CA.O=IBM.C=US LEVEL OWNER UNIVERSAL ACCESS YOUR ACCESS WARNING --- --- --- --- --- 00 ANTOFF ALTER ALTER NO INSTALLATION DATA --- NONE APPLICATION DATA --- WEBSTU --- ---
LIST key ring
Now we list our key rings.
For user ID PKISTU
The command to list the key ring is:
RACDCERT ID(PKISTU) LISTRING(CARING)
Table 2-23 shows the output.
Example 2-23 List of the key ring for PKISTU
Digital ring information for user PKISTU: Ring: >CARING< Certificate Label Name Cert Owner USAGE DEFAULT
Note: The only difference between the profile for our Web server certificate
and the profile for our CA certificate is the serial number. The APPLDATA field contains the user ID associated with certificate: the Web server started task user ID: WEBSTU.
Note: The keyword ID( ) must always be used to list any key ring. Also ID( )
Chapter 2. RACF for PKI Services 75
--- --- --- --- IBM ITSO PSIE PKI1 CERTAUTH PERSONAL YES
The output from RLIST PKISTU.CARING ALL is shown in Example 2-24.
Example 2-24 Output of RLIST PKISTU
CLASS NAME --- ---- DIGTRING PKISTU.CARING LEVEL OWNER UNIVERSAL ACCESS YOUR ACCESS WARNING --- --- --- --- --- 00 ANTOFF NONE NONE NO INSTALLATION DATA --- NONE APPLICATION DATA --- PKISTU SECLEVEL --- NO SECLEVEL CATEGORIES --- NO CATEGORIES SECLABEL --- NO SECLABEL AUDITING --- FAILURES(READ) GLOBALAUDIT --- NONE NOTIFY --- NO USER TO BE NOTIFIED
CREATION DATE LAST REFERENCE DATE LAST CHANGE DATE (DAY) (YEAR) (DAY) (YEAR) (DAY) (YEAR) --- --- ---
120 03 120 03 120 03 ALTER COUNT CONTROL COUNT UPDATE COUNT READ COUNT --- --- --- --- 000000 000000 000000 000000 USER ACCESS ACCESS COUNT ---- --- --- --- NO USERS IN ACCESS LIST ID ACCESS ACCESS COUNT CLASS ENTITY NAME --- --- --- --- --- NO ENTRIES IN CONDITIONAL ACCESS LIST
For user ID WEBSTU
Example 2-25 Listing key ring of Web server
Digital ring information for user WEBSTU: Ring: >SSLRING< Certificate Label Name Cert Owner USAGE DEFAULT --- --- --- --- IBM ITSO PSIE PKI1 CERTAUTH PERSONAL NO SSL PKI1 ID(WEBSTU) PERSONAL YES