RACDCERT ALTER (Alter certificate)

Purpose

Use the RACDCERT ALTER command to change the status or the label of a digital certificate for the specified user ID, certificate-authority certificate, or site certificate.

Restriction: Because PKCS #11 tokens are managed by ICSF, not RACF®, when you use the RACDCERT ALTER command to alter a certificate that is bound in a token, the change is not reflected on the corresponding certificate object in the token.

See UTF-8 and BMP character restrictions for information about how UTF-8 and BMP characters in certificate names and labels are processed by RACDCERT functions.

Issuing options

The following table identifies the eligible options for issuing the RACDCERT ALTER command:
As a RACF TSO command? As a RACF operator command? With command direction? With automatic command direction? From the RACF parameter library?
Yes No No. (See rules.) No. (See rules.) No
Rules: The following rules apply when issuing this command.
  • The RACDCERT command cannot be directed to a remote system using the AT or ONLYAT keyword.
  • The updates made to the RACF database by RACDCERT are eligible for propagation with automatic direction of application updates based on the RRSFDATA profiles AUTODIRECT.target-node.DIGTCERT.APPL and AUTODIRECT.target-node.DIGTRING.APPL, where target-node is the remote node to which the update is to be propagated.

Authorization required

To issue the RACDCERT ALTER command, you must have the following authorizations:
  • The SPECIAL attribute, or
  • Sufficient authority to the IRR.DIGTCERT.ALTER resource in the FACILITY class, as shown in Table 1, or
  • Sufficient authority to the appropriate resources in the RDATALIB class, as shown in Table 2, if Granular Authority Checking has been enabled by defining the IRR.RACDCERT.GRANULAR resource in the RDATALIB class.
Table 1. Authority required for the RACDCERT ALTER function under the FACILITY class
Access level Purpose
READ Change the trust status or label of your own certificate.
UPDATE Change the trust status or label of another user's certificate.
CONTROL Change the trust status or label of a SITE or CERTAUTH certificate.
Table 2. Authority required for the RACDCERT ALTER function under the RDATALIB class when IRR.RACDCERT.GRANULAR is defined
READ access to the resource based on cert owner and cert label * Purpose
IRR.DIGTCERT.<cert owner>.<cert label>.UPD.ALTER Alter a certificate status under <cert owner> with specified <cert label>
IRR.DIGTCERT.<cert owner>.<source cert label>.UPD.ALTER,
and
IRR.DIGTCERT.<cert owner>.<target cert label>.UPD.ALTER
 Alter a certificate label under <cert owner> with specified <source cert label> and <target cert label>
* 'cert owner' is the RACF user ID, or CERTIFAUTH (for CERTAUTH), or SITECERTIF (for SITE)

Activating your changes

If the DIGTCERT or DIGTRING class is RACLISTed, refresh the classes to activate your changes.

Example: 
SETROPTS RACLIST(DIGTCERT, DIGTRING) REFRESH

Related commands

Syntax

For the key to the symbols used in the command syntax diagrams, see Syntax of RACF commands and operands. The complete syntax of the RACDCERT ALTER command is:

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.

For information on issuing this command as a RACF TSO command, refer to RACF TSO commands.

Parameters

ALTER(LABEL('label-name'))
ALTER(SERIALNUMBER(serial-number) ISSUERSDN('issuer's-dn'))
The TRUST, NOTRUST, or NEWLABEL keyword must be specified with the ALTER keyword. If the user has only one certificate, the SERIALNUMBER and ISSUERSDN keywords, or the LABEL keyword, and their associated values can be omitted. If the user has more than one certificate the LABEL, SERIALNUMBER, or SERIALNUMBER and ISSUERSDN must be used to specify which certificate to alter.

When specifying the issuer's distinguished name or the label, you must specify any mixed-case or blank characters exactly as they appear in the output of the RACDCERT LIST command for the certificate.

Restriction: The ISSUERSDN keyword is not supported for lengthy issuer's distinguished names when the name of the certificate's DIGTCERT profile contains a certificate hash value. For more information about DIGTCERT profile names, see the "Purpose" topic of RACDCERT ADD.

For a description of label-name, see the WITHLABEL keyword for RACDCERT ADD.

Note that the only alterable certificate information is the TRUST status or the label of a certificate.

ID(certificate-owner) | SITE | CERTAUTH
Specifies that the certificate to alter is either a user certificate associated with the specified user ID, a site certificate, or a certificate-authority certificate. If you do not specify ID, SITE, or CERTAUTH, the default is ID, and certificate-owner defaults to the user ID of the command issuer. If more than one keyword is specified, the last specified keyword is processed and the others are ignored by TSO command parse processing.
TRUST | NOTRUST | HIGHTRUST
Specifies whether the status of the certificate being altered is trusted, not trusted, or highly trusted. If TRUST, NOTRUST, or HIGHTRUST is not specified with the ALTER keyword, no change to the status of the certificate is attempted.

For a detailed description, see the TRUST, NOTRUST, HIGHTRUST keyword for RACDCERT ADD.

NEWLABEL('new-label-name')
Specifies the label replacing the previous label (if there was one specified) that is assigned to a certificate.

See the WITHLABEL keyword for RACDCERT ADD for information on label rules.

If new-label-name is the same as label-name, the label is not changed and no message is issued.

Examples

Example Activity label Description
1 Operation User CADUDE with CONTROL access to FACILITY class profile IRR.DIGTCERT.* wants to mark the local certificate authority highly trusted.
Known User CADUDE has CONTROL authority to the profile IRR.DIGTCERT.* in the FACILITY class.
Command 
RACDCERT CERTAUTH ALTER(LABEL('Local PKIX CA')) HIGHTRUST
Output None.