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

Authority required includes appropriate access to:
  1. the resource(s) in the FACILITY class which is based on the RACDCERT function, or
  2. the resource(s) in the RDATALIB class which is based on the RACDCERT function, the certificate owner, the certificate label, the ring owner and the ring name specified for the command. If they are not explicitly specified, the default values will be used to form the resource.

    This authority checking mechanism provides granular control on a subset of RACDCERT functions: ADD, ADDRING, ALTER, CONNECT, DELETE, DELRING, EXPORT, GENCERT, GENREQ, IMPORT, REKEY, REMOVE and ROLLOVER, if IRR.RACDCERT.GRANULAR is defined in the RDATALIB class. Note: Don't define IRR.RACDCERT.GRANULAR before granular profiles are set up. Otherwise these RACDCERT functions will fail the authorization check.

  3. the resources in the CSFSERV, CSFKEY or CRYPTOZ classes if the key is stored or managed by ICSF
For authorization details about each RACDCERT function, see the "Authorization required" topic under each 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. Enforce a naming convention on the certificate labels and key ring names and segregate the administration if needed.
  • 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.
EXAMPLES:

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 establishes access control over keys that are stored in ICSF and the RACDCERT command that is used has a reference to a key stored in PKDS, the issuers of the RACDCERT command must have READ access authority to key label that is controlled by the profile in the CSFKEYS class. You can reference a key that is stored in PKDS through the RACDCERT command either explicitly (by using GENCERT, ADD, or REKEY) or implicitly (by using GENREQ or DELETE).

If a key label is not supplied (either specified or derived from the certificate label) through the RACDCERT command, a system generated label is created in the format of IRR.DIGTCERT.certificate-owner.cvtsname.ebcdic-stck-value, where certificate-owner is user ID, CERTIFAUTH or SITECERTIF. The cvtsname is the system name that is taken from CVT and ebcdic-stck-value is an EBCDIC version of the current store-clock value.

If you always want to use the system generated key label, you can define a generic profile in the CSFKEYS class to protect the key. For example, by using IRR.DIGTCERT.CERTIFAUTH.*.

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 more information about 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 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.

Certificate Date and Time value considerations

These considerations pertain to the following functions that involve the setting and displaying of the date and time values in a certificate:
  • GENCERT
  • REKEY
  • LIST
  • LISTCHAIN
  • CHECKCERT

Since the specified or default date and time values are treated as local time, internal command processing converts the values to Universal Time Coordinated (UTC) by using the difference between the local and UTC time that is defined on the system. The converted UTC date and time values are stored in the certificate.

If the local time on the system is rolled back approximately 204 days from the UTC time on the system, the certificate validity dates are not computed correctly and unpredictable dates are stored in the certificate.

Key ring name handling in a profile

For functions that involve key ring – ADDRING, DELRING, CONNECT, REMOVE, we use similar rules that apply to R_datalib, documented in the RACF Callable Service book.

The ringOwner must be in uppercase. The ringName is folded into uppercase during profile checking.
Note: ringNames which differ only in case use the same profile.

If the constructed profile based on the ringOwner, ringName and function name has reached the field size limits, and you want to create a discrete profile, you can truncate the ring name from the end to make the whole profile name length 246 characters.

For example, if the owner ID is JOESMITH and the ring name is:
  • THISISARINGWITH237CHARACTERS...REACHINGRINGEND (with a length of 237)
    the discrete profile for ADDRING will be
    JOESMITH.THISISARINGWITH237CHARACTERS...REA.UPD.ADDRING
  • The discrete profile for REMOVE will be
    JOESMITH.THISISARINGWITH237CHARACTERS...REAC.UPD.REMOVE
  • If the owner ID is J, the profile for REMOVE will be
    J.THISISARINGWITH237CHARACTERS...REACHINGRIN.UPD.REMOVE

Certificate label handling in a profile

The certificate label is part of the profile, but the characters in a label and in the profile do not follow the same set of rules. For example, the certificate label can contain special characters like *, which is considered a generic character in the profile; the label can contain blanks, but the profile can not; the label is case sensitive but the profile is not.

The label part will be modified as follows in the construction of the resource profile:
  1. blank( ), comma(,), back slash(\), ampersand(&), asterisk(*) and percent(%) will be replaced with underscore (_, X’6D’)
  2. will be folded into uppercase
With these restrictions, the certificates that have labels differ only in case, with blanks or special characters may be covered by the same profile.
Example 1: IRR.DIGTCERT.JOSH.MY_CERT.UPD.ALTER will cover the following certificate labels that belong to Josh:
  • MY_CERT
  • My_Cert
  • My CERT
  • My%cert
  • My\Cert
  • my&cert
  • my*cert
  • ...
Example 2: IRR.DIGTCERT.JOSH.MY*.UPD.DELETE will cover the following certificate labels that belong to Josh:
  • MY*CERT
  • MyfirstCERT
  • MyCA
  • …
Example 3: IRR.DIGTCERT.JOSH.MY_*.UPD.DELETE will cover the following certificate labels that belong to Josh:
  • MY*CERT
  • My*firstCERT
  • My*CA
  • …

The function CLBL in the sample program IRRICE in SYS1.SAMPLIB can be used to find out the certificate labels that will result to the same string after the conversion so that the customer can alter them if they want to avoid using the same discrete profile to protect multiple labels.