RACDCERT (Manage RACF digital certificates)

The RACDCERT command has numerous functions. Each function of the RACDCERT command is documented in a separate topic that contains its purpose, authorization required, syntax, and other specific information.

For details about each RACDCERT function, see the following topics:

Purpose

Use the RACDCERT command to install and maintain digital certificates, key rings, and digital certificate mappings in RACF®. RACDCERT should be used for all maintenance of profiles in the DIGTCERT, DIGTRING, and DIGTNMAP classes.

The RACDCERT command is a RACF TSO command used to:

List information about the certificates for a specified RACF-defined user ID, or your own user ID.
Add a certificate and associate it with a specified RACF-defined user ID, or your own user ID, and set the TRUST status.
Check to see if a certificate has been defined to RACF.
Alter the TRUST status or label for a certificate.
Delete a certificate.
List a certificate or a chain of certificates contained in a data set and determine if it is associated with a RACF-defined user ID.
Add or remove a certificate from a key ring.
Create, delete, or list a key ring.
Generate a public/private key pair and certificate, replicate a digital certificate with a new public/private key pair, or retire the use of an existing private key.
Write (export) a certificate or certificate package to a data set.
Create a certificate request.
Create, alter, delete, or list a certificate name filter (user ID mapping).
Add, delete, or list a z/OS PKCS #11 token.
Bind a certificate to a z/OS PKCS #11 token.
Remove (unbind) a certificate from a z/OS PKCS #11 token.
Import a certificate (with its private key, if present) from a z/OS PKCS #11 token and add it to RACF.

RACF supports RSA, DSA, and ECC keys. The key value can reside in the RACF database in a DER encoded format, or in the ICSF PKA key data set or ICSF token key data set (TKDS). If the key is in ICSF, its location, not the value, is stored in the RACF database.

RACF signs its certificates using a set of secure hash algorithms based on the SHA-1 or SHA-2 hash functions.

For increased security and performance of signature verifications, RACF uses an exponent value of 65537 for each key it generates with the RSA algorithm.

Authorization required

To issue the RACDCERT command, you must have sufficient authority for the specific RACDCERT function. This authority may include one or all of the following, depending on the command function.

SPECIAL, or sufficient authority to the appropriate resource in the FACILITY class.
Sufficient access to the appropriate resource in the CSFSERV class when your installation controls access to ICSF services and the CSFSERV class is active.
Sufficient ICSF authority to the appropriate resource in the CRYPTOZ class.
For details about CSFSERV and CRYPTOZ resources, see z/OS Cryptographic Services ICSF Administrator's Guide.

For authorization details about each RACDCERT function, see the "Authorization required" topic for the RACDCERT function.

Controlling the use of RACDCERT: Effective use of RACDCERT requires that its privileges be carefully controlled. However, end users and application administrators should be allowed some flexibility in defining their security characteristics.

Guidelines:

Give the authority to add certificate authorities to only a small set of trusted people.
End users need to add, delete, and modify the contents of their own key rings and to add, delete, and alter their own certificates.
Help desk personnel need to list certificates and key rings.

Example: ich2a400-obj2.htm#ich2a400-gen2__rdauth1 lists sample commands to implement one method of controlling RACDCERT access according to these guidelines. In the example shown, the system administrators (who are the only ones to add, alter, or delete certificate-authority certificates or site certificates) are in the WEBADMIN group and the help desk personnel are in the HELPDESK group.

Syntax

For details about syntax and parameters for each RACDCERT function, see the "Syntax" and "Parameters" subtopics of each RACDCERT function.

If you specify more than one RACDCERT function, only the last specified function is processed. Extraneous keywords that are not related to the function being performed are ignored.

If you do not specify a RACDCERT function, LIST is the default function.

UTF-8 and BMP character restrictions

You can include UTF-8 and BMP characters in certificate names with the following restrictions:

You can specify certificate names that include UTF-8 and BMP characters only when they are part of an encoded certificate or certificate request that is stored in an MVS data set, and you specify the data set name with your RACDCERT command.
Do not use keyboard entries (including cut-and-paste methods) to specify UTF-8 and BMP characters as command-line input. UTF-8 or BMP characters specified at the command line might be incorrectly processed, although you might receive no input error.
Any UTF-8 or BMP character that does not map to the IBM-1047 code page is represented by six characters in the U+nnnn format, where nnnn is the hexadecimal form of the Unicode code point for the UTF-8 or BMP character. For example, the Euro symbol (€) is represented as U+20AC.
For a sample listing of a certificate that contains information that includes an unmapped character, see Figure 6.
When one unmapped UTF-8 or BMP character is represented by six characters, the additional five characters of length might affect the processing of certain certificates, such as in the following cases:
- When the issuer's distinguished name is lengthy and contains one or more unmapped UTF-8 or BMP characters, the resulting profile name for the certificate might exceed the allowable length for a profile name. If this occurs, the RACDCERT ADD or GENCERT command fails and the certificate is not added.
- When RACF generates a default label for a certificate extracted from a PKCS #12 package during RACDCERT ADD processing and the certificate's friendly name contains one or more unmapped UTF-8 or BMP characters, the resulting label might exceed 32 characters. If this occurs, RACF truncates the label.

DEBUG keyword

Add the DEBUG keyword when you issue the RACDCERT command to obtain additional diagnostic messages for failures related to encryption calls, and RACF-invoked ICHEINTY ALTER, RACROUTE REQUEST=EXTRACT, and RACROUTE REQUEST=DEFINE calls.

The content of these additional diagnostic messages are not documented in the RACF publication library.

If you report a problem to the IBM® Support Center, use the DEBUG keyword to gather diagnostic information.

ICSF considerations

RACDCERT processing makes use of ICSF services. When your installation controls access to ICSF services and the CSFSERV class is active, issuers of certain RACDCERT command functions might require additional access to CSFSERV resources. For complete details, see the "Authorization required" topic of each RACF command function.

Restriction: When ICSF is operating in FIPS mode, the following RACDCERT functions do not support Brainpool ECC keys:

ADD
EXPORT
GENCERT
GENREQ
IMPORT
REKEY

If your installation has established access control over keys stored in ICSF, the issuers of the RACDCERT command must have READ access authority to ICSF keys by label. Because the specific label values might be difficult to determine, generic profiles are suggested according to Table 1, based on the issued RACDCERT function and the attributes of the ICSF key.

Table 1. Suggested generic profiles (resources in the CSFKEYS class) that authorize access to ICSF keys based on RACDCERT function and key attributes
RACDCERT command	Keywords	Suggested generic profile (CSFKEYS class resource)
ADD, GENCERT or REKEY for ID(cert-owner)	PKDS, ICSF, or PCICC	IRR.DIGTCERT.cert-owner`.*`
ADD, GENCERT or REKEY for CERTAUTH	PKDS, ICSF, or PCICC	IRR.DIGTCERT.CERTIFAUTH`.*`
ADD, GENCERT or REKEY for SITE	PKDS, ICSF, or PCICC	IRR.DIGTCERT.SITECERTIF`.*`
GENCERT for ID(cert-owner)	SIGNWITH(LABEL('label'))	IRR.DIGTCERT.cert-owner`.*`
GENCERT	SIGNWITH(CERTAUTH LABEL('label'))	IRR.DIGTCERT.CERTIFAUTH`.*`
GENCERT	SIGNWITH(SITE LABEL('label'))	IRR.DIGTCERT.SITECERTIF`.*`
GENREQ or DELETE for ID(cert-owner)	-	IRR.DIGTCERT.cert-owner`.*`
GENREQ or DELETE for CERTAUTH	-	IRR.DIGTCERT.CERTIFAUTH`.*`
GENREQ or DELETE for SITE	-	IRR.DIGTCERT.SITECERTIF`.*`

Additionally, the user ID assigned to an application, such as System SSL, that uses certificates stored in RACF key rings also needs READ authority to ICSF keys by label. Because the specific label values might be difficult to determine, generic profiles are suggested according to Table 2, based on the CONNECT attributes of the ICSF key.

Table 2. Suggested generic profiles (resources in the CSFKEYS class) that authorize access to ICSF keys based on CONNECT attributes
RACDCERT CONNECT keywords used to populate the key ring	Suggested generic profile (CSFKEYS class resource)
CONNECT(LABEL('label')) for ID(cert-owner)	IRR.DIGTCERT.cert-owner`.*`
CONNECT(CERTAUTH LABEL('label') USAGE(PERSONAL))	IRR.DIGTCERT.CERTIFAUTH`.*`
CONNECT(SITE LABEL('label-name') USAGE(PERSONAL))	IRR.DIGTCERT.SITECERTIF`.*`

Sufficient ICSF authority for the following command functions is controlled using resources in the CRYPTOZ class. If the CSFSERV class is active, sufficient ICSF authority for the following command functions might also be required. For authorization details, see z/OS Cryptographic Services ICSF Administrator's Guide.

ADDTOKEN
BIND
DELTOKEN
IMPORT
LISTTOKEN
UNBIND

Hardware requirements

The following hardware features are required on the system when you issue the ADD, GENCERT, IMPORT, or REKEY functions to store a key in the ICSF PKA key data set (PKDS) or in the ICSF token data set (TKDS). These features are also required on any system where a user or SSL application accesses the key.

The ICSF subsystem must be operational and configured for PKA operations. Otherwise, command processing stops and an error message is displayed.
The cryptographic coprocessor must be operational and configured to use the PKDS or TKDS where the key is to be stored or accessed.
- CCA cryptographic coprocessor is required to process keys stored in the PKDS.
  - A Crypto Express3 coprocessor (CEX3C), or later, is required to process ECC PKDS keys.
- Enterprise PKCS#11 cryptographic coprocessor is required to process secure keys stored in the TKDS.

PKDS label considerations

When you specify the PKDS, ICSF, or PCICC keyword with the ADD, GENCERT, IMPORT, or REKEY function, RACF stores the key in the ICSF PKA key data set (PKDS).

Setting a PKDS label for the key is optional. You can specify a label or you can specify an asterisk (*) to use the certificate label from the WITHLABEL keyword as the PKDS label for the key. If you specify an asterisk (*), you must specify the WITHLABEL keyword.

Whether specified or taken from the WITHLABEL keyword, the PKDS label must be unique and conform to ICSF syntax requirements. That is, allowed characters are alphanumeric, national (@, #, $), or period (.). Blank characters are not allowed. The first character must be alphabetic or national. The label must be 1 - 64 characters and is translated to uppercase (not case-sensitive).

If the specified PKDS label, or the certificate label (when you specify an asterisk), does not conform to ICSF syntax requirements, it cannot be used as the PKDS label and the command fails.

When you do not specify a PKDS label and you do not specify an asterisk (*), RACF generates a default label in the format IRR.DIGTCERT.certificate-owner.cvtsname.ebcdic-stck-value, where certificate-owner is the owning user ID, cvtsname is the system name (taken from the CVT), and ebcdic-stck-value is an EBCDIC version of the current store-clock value. RACF does not generate a PKDS label for a public key.

Note: When the key is associated with a certificate-authority certificate, the owning user ID is set to CERTIFAUTH. When the key is associated with a site certificate, then the owning user ID is set to SITECERTIF.

Examples

Figure 1. Controlling access to RACDCERT functions

RDEFINE FACILITY IRR.DIGTCERT.ADD       UACC(NONE)
RDEFINE FACILITY IRR.DIGTCERT.ADDRING   UACC(NONE)
RDEFINE FACILITY IRR.DIGTCERT.ALTER     UACC(NONE)
RDEFINE FACILITY IRR.DIGTCERT.ALTMAP    UACC(NONE)
RDEFINE FACILITY IRR.DIGTCERT.BIND      UACC(NONE)
RDEFINE FACILITY IRR.DIGTCERT.CONNECT   UACC(NONE)
RDEFINE FACILITY IRR.DIGTCERT.DELETE    UACC(NONE)
RDEFINE FACILITY IRR.DIGTCERT.DELMAP    UACC(NONE)
RDEFINE FACILITY IRR.DIGTCERT.DELRING   UACC(NONE)
RDEFINE FACILITY IRR.DIGTCERT.EXPORT    UACC(NONE)
RDEFINE FACILITY IRR.DIGTCERT.EXPORTKEY UACC(NONE)
RDEFINE FACILITY IRR.DIGTCERT.GENCERT   UACC(NONE)
RDEFINE FACILITY IRR.DIGTCERT.GENREQ    UACC(NONE)
RDEFINE FACILITY IRR.DIGTCERT.LIST      UACC(NONE)
RDEFINE FACILITY IRR.DIGTCERT.LISTMAP   UACC(NONE)
RDEFINE FACILITY IRR.DIGTCERT.LISTRING  UACC(NONE)
RDEFINE FACILITY IRR.DIGTCERT.MAP       UACC(NONE)
RDEFINE FACILITY IRR.DIGTCERT.REKEY     UACC(NONE)
RDEFINE FACILITY IRR.DIGTCERT.REMOVE    UACC(NONE)
RDEFINE FACILITY IRR.DIGTCERT.ROLLOVER  UACC(NONE)

PERMIT IRR.DIGTCERT.ADD       CLASS(FACILITY) ID(WEBADMIN) ACCESS(CONTROL)
PERMIT IRR.DIGTCERT.ADDRING   CLASS(FACILITY) ID(WEBADMIN) ACCESS(UPDATE)
PERMIT IRR.DIGTCERT.ALTER     CLASS(FACILITY) ID(WEBADMIN) ACCESS(CONTROL)
PERMIT IRR.DIGTCERT.ALTMAP    CLASS(FACILITY) ID(WEBADMIN) ACCESS(UPDATE)
PERMIT IRR.DIGTCERT.BIND      CLASS(FACILITY) ID(WEBADMIN) ACCESS(CONTROL)
PERMIT IRR.DIGTCERT.CONNECT   CLASS(FACILITY) ID(WEBADMIN) ACCESS(CONTROL)
PERMIT IRR.DIGTCERT.DELETE    CLASS(FACILITY) ID(WEBADMIN) ACCESS(CONTROL)
PERMIT IRR.DIGTCERT.DELMAP    CLASS(FACILITY) ID(WEBADMIN) ACCESS(UPDATE)
PERMIT IRR.DIGTCERT.DELRING   CLASS(FACILITY) ID(WEBADMIN) ACCESS(UPDATE)
PERMIT IRR.DIGTCERT.EXPORT    CLASS(FACILITY) ID(WEBADMIN) ACCESS(CONTROL)
PERMIT IRR.DIGTCERT.EXPORTKEY CLASS(FACILITY) ID(WEBADMIN) ACCESS(CONTROL)
PERMIT IRR.DIGTCERT.GENCERT   CLASS(FACILITY) ID(WEBADMIN) ACCESS(CONTROL)
PERMIT IRR.DIGTCERT.GENREQ    CLASS(FACILITY) ID(WEBADMIN) ACCESS(CONTROL)
PERMIT IRR.DIGTCERT.LIST      CLASS(FACILITY) ID(WEBADMIN) ACCESS(CONTROL)
PERMIT IRR.DIGTCERT.LISTMAP   CLASS(FACILITY) ID(WEBADMIN) ACCESS(UPDATE)
PERMIT IRR.DIGTCERT.LISTRING  CLASS(FACILITY) ID(WEBADMIN) ACCESS(UPDATE)
PERMIT IRR.DIGTCERT.MAP       CLASS(FACILITY) ID(WEBADMIN) ACCESS(UPDATE)
PERMIT IRR.DIGTCERT.REKEY     CLASS(FACILITY) ID(WEBADMIN) ACCESS(CONTROL)
PERMIT IRR.DIGTCERT.REMOVE    CLASS(FACILITY) ID(WEBADMIN) ACCESS(CONTROL)
PERMIT IRR.DIGTCERT.ROLLOVER  CLASS(FACILITY) ID(WEBADMIN) ACCESS(CONTROL)

PERMIT IRR.DIGTCERT.ADD       CLASS(FACILITY) ID(*) ACCESS(READ)
PERMIT IRR.DIGTCERT.ADDRING   CLASS(FACILITY) ID(*) ACCESS(READ)
PERMIT IRR.DIGTCERT.ALTER     CLASS(FACILITY) ID(*) ACCESS(READ)
PERMIT IRR.DIGTCERT.ALTMAP    CLASS(FACILITY) ID(*) ACCESS(READ)
PERMIT IRR.DIGTCERT.BIND      CLASS(FACILITY) ID(*) ACCESS(READ)
PERMIT IRR.DIGTCERT.CONNECT   CLASS(FACILITY) ID(*) ACCESS(READ)
PERMIT IRR.DIGTCERT.DELETE    CLASS(FACILITY) ID(*) ACCESS(READ)
PERMIT IRR.DIGTCERT.DELMAP    CLASS(FACILITY) ID(*) ACCESS(READ)
PERMIT IRR.DIGTCERT.DELRING   CLASS(FACILITY) ID(*) ACCESS(READ)
PERMIT IRR.DIGTCERT.EXPORT    CLASS(FACILITY) ID(*) ACCESS(READ)
PERMIT IRR.DIGTCERT.EXPORTKEY CLASS(FACILITY) ID(*) ACCESS(READ)
PERMIT IRR.DIGTCERT.GENCERT   CLASS(FACILITY) ID(*) ACCESS(READ)
PERMIT IRR.DIGTCERT.GENREQ    CLASS(FACILITY) ID(*) ACCESS(READ)
PERMIT IRR.DIGTCERT.LIST      CLASS(FACILITY) ID(*) ACCESS(READ)
PERMIT IRR.DIGTCERT.LISTMAP   CLASS(FACILITY) ID(*) ACCESS(READ)
PERMIT IRR.DIGTCERT.LISTRING  CLASS(FACILITY) ID(*) ACCESS(READ)
PERMIT IRR.DIGTCERT.MAP       CLASS(FACILITY) ID(*) ACCESS(READ)
PERMIT IRR.DIGTCERT.REKEY     CLASS(FACILITY) ID(*) ACCESS(READ)
PERMIT IRR.DIGTCERT.REMOVE    CLASS(FACILITY) ID(*) ACCESS(READ)
PERMIT IRR.DIGTCERT.ROLLOVER  CLASS(FACILITY) ID(*) ACCESS(READ)

PERMIT IRR.DIGTCERT.LIST      CLASS(FACILITY) ID(HELPDESK) ACCESS(CONTROL)
PERMIT IRR.DIGTCERT.LISTMAP   CLASS(FACILITY) ID(HELPDESK) ACCESS(UPDATE)
PERMIT IRR.DIGTCERT.LISTRING  CLASS(FACILITY) ID(HELPDESK) ACCESS(UPDATE)