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.
- RACDCERT ADD (Add certificate)
- RACDCERT ADDRING (Add key ring)
- RACDCERT ADDTOKEN (Add token)
- RACDCERT ALTER (Alter certificate)
- RACDCERT ALTMAP (Alter mapping)
- RACDCERT BIND (Bind certificate to token)
- RACDCERT CHECKCERT (Check certificate or certificate chain)
- RACDCERT CONNECT (Connect a certificate to key ring)
- RACDCERT DELETE (Delete certificate)
- RACDCERT DELMAP (Delete mapping)
- RACDCERT DELRING (Delete key ring)
- RACDCERT DELTOKEN (Delete token)
- RACDCERT EXPORT (Export certificate package)
- RACDCERT GENCERT (Generate certificate)
- RACDCERT GENREQ (Generate request)
- RACDCERT IMPORT (Import certificate)
- RACDCERT LIST (List certificate)
- RACDCERT LISTCHAIN (List certificate chain)
- RACDCERT LISTMAP (List mapping)
- RACDCERT LISTRING (List key ring)
- RACDCERT LISTTOKEN (List token)
- RACDCERT MAP (Create mapping)
- RACDCERT REKEY (Rekey certificate)
- RACDCERT REMOVE (Remove certificate from key ring)
- RACDCERT ROLLOVER (Rollover certificate)
- RACDCERT UNBIND (Unbind certificate from token).
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
- the resource(s) in the FACILITY class which is based on the RACDCERT function, or
- 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.
- the resources in the CSFSERV, CSFKEY or CRYPTOZ classes if the key is stored or managed by ICSF
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.
- 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.
- Example commands to implement one method of controlling RACDCERT access, according to these guidelines, using the FACILITY class are listed in Examples of controlling access to RACDCERT functions using the FACILITY class.
- Examples shown in Examples of controlling the use of the RACDCERT command using the RDATALIB class lists the granular control on naming convention on the certificate label and key ring name used in the system using the RDATALIB class.
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 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 asU+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.
- 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.*.
- ADDTOKEN
- BIND
- DELTOKEN
- IMPORT
- LISTTOKEN
- UNBIND
Hardware requirements
- 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 with the 32 bytes ECC master key activated to process RSA and ECC PKDS keys.
- Enterprise PKCS#11 cryptographic coprocessor is required to process secure keys stored in the TKDS.
- CCA cryptographic coprocessor is required to process keys stored
in the PKDS.
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.
Certificate Date and Time value considerations
- 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.
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.
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.
- blank( ), comma(,), back slash(\), ampersand(&), asterisk(*) and percent(%) will be replaced with underscore (_, X’6D’)
- will be folded into uppercase
- MY_CERT
- My_Cert
- My CERT
- My%cert
- My\Cert
- my&cert
- my*cert
- ...
- MY*CERT
- MyfirstCERT
- MyCA
- …
- 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.