RACDCERT ROLLOVER (Rollover certificate)

Purpose

Use the RACDCERT ROLLOVER command to supersede one certificate (the source certificate) with another certificate (the target certificate). In general, issue the RACDCERT ROLLOVER command after issuing the RACDCERT REKEY command to supersede an old, expiring certificate with a new rekeyed certificate, and to retire the private key of the expiring certificate. For sample procedures, see "Renewing a certificate with a new private key (rekeying)" in z/OS Security Server RACF Security Administrator's Guide.

Both the source and target certificates are associated with the user ID, CERTAUTH, or SITE as specified on the command. RACDCERT ROLLOVER processing performs the following actions in the specified order:

Deletes the private key of the source certificate so that it may not be used again for any cryptographic operations that need the private key. For example, signing another certificate or decrypting data encrypted via the certificate's public key.
Adds the target certificate to any key ring that contains the source certificate and, depending on how the source certificate is connected to the ring, RACDCERT ROLLOVER processing also does one of the following actions:
- If the source certificate is connected with PERSONAL usage, the source certificate is replaced by the target certificate. In other words, the new certificate is added to the ring and the old one is removed.
- If the source certificate is connected with CERTAUTH or SITE usage, the target certificate is added to the key ring and the source certificate remains connected. In other words, the new certificate is added to the ring but the old one is not removed.
Copies the serial number base from the source certificate to the target certificate. The serial number base is the serial number of the last certificate that this certificate issued.

Once rollover is complete, the new certificate may be used as if it were the old certificate. The old certificate is retained for historical reasons such as validating signatures on existing certificates, but may no longer be used for any private key operations such as signing other certificates.

Issuing options

The following table identifies the eligible options for issuing the RACDCERT ROLLOVER 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 ROLLOVER command, you must have the SPECIAL attribute or sufficient authority to the IRR.DIGTCERT.ROLLOVER resource in the FACILITY class for your intended purpose.

Table 1. Authority required for the RACDCERT ROLLOVER function
IRR.DIGTCERT.ROLLOVER
Access level	Purpose
READ	Rollover your own certificate.
UPDATE	Rollover another user's certificate.
CONTROL	Rollover a SITE or CERTAUTH certificate.

If the private key of the source certificate is stored in the ICSF PKA key data set (PKDS), you must have READ access to the CSFPKRD resource.

If the private key of the source certificate is stored in the ICSF Token Data Set (TKDS), you must have READ access to the CSF1TRD resource.

Activating your changes

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

Example:

SETROPTS RACLIST(DIGTCERT) REFRESH

Related commands

To rekey a expiring certificate, see RACDCERT REKEY (Rekey certificate).

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 ROLLOVER command is:


RACDCERT ROLLOVER(LABEL('old-label-name'))
[ ID(certificate-owner) \| SITE \| CERTAUTH ] NEWLABEL('new-label-name') [ FORCE ]

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

ROLLOVER(LABEL('old-label-name'))

Specifies the label of the source certificate to be superseded by the certificate with the 'new-label-name' label.

ID(certificate-owner) | SITE | CERTAUTH

Specifies that both certificates identified by LABEL and NEWLABEL are either user certificates associated with the specified user ID, site certificates, or a certificate-authority certificates. 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.

NEWLABEL('new-label-name')

Specifies the label of the target certificate for the rollover function. This keyword is required and must identity an existing certificate owned by the specified user ID, SITE, or CERTAUTH.

FORCE

Specifies that RACF should bypass the following error checking and unconditionally perform the rollover operation.

If you do not specify FORCEto bypass these conditions, an error message is issued and the command ends:

The values specified for the LABEL and NEWLABEL keywords are the same.
The certificate identified by the LABEL or NEWLABEL keywords does not have a private key associated with it.
The certificate identified by the NEWLABEL keyword has been the target certificate of a previously issued RACDCERT ROLLOVER command.
The certificate identified by the NEWLABEL keyword has been used to sign other certificates.
The certificate being superseded has been used to generate a request through RACDCERT GENREQ.

If you specify FORCE, these conditions are not checked. If you specify FORCE and inadvertently specify the same certificate with both the LABEL and NEWLABEL keywords, the private key of this certificate is deleted.

Examples


Example 1	Operation	User RACFADM has an expiring CERTAUTH certificate labeled `'Local PKI CA'` and wants to retire it and replace it with a new, rekeyed certificate labeled `'Local PKI CA-2'`.
	Known	User RACFADM has CONTROL access to the IRR.DIGTCERT.ROLLOVER resource in the FACILITY class.
	Command	`RACDCERT ROLLOVER(LABEL(’Local PKI CA’)) CERTAUTH NEWLABEL(’Local PKI CA-2’)`
	Output	None.