RACDCERT UNBIND (Unbind certificate from token)

Purpose

Removes a digital certificate from the specified z/OS® PKCS #11 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 UNBIND 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

Authorization to delete z/OS PKCS #11 tokens is controlled by ICSF based on profiles in the CRYPTOZ class. (No authority in the FACILITY class is required.) If you do not have authority to remove the certificate from the specified token as determined by ICSF, the command stops and an error message is displayed.

When your installation controls access to ICSF services and the CSFSERV class is active, you must also have READ access to the CSF1GAV, CSF1TRD, and CSF1TRL resources in the CSFSERV class.

For authorization details about the CRYPTOZ and CSFSERV classes, see z/OS Cryptographic Services ICSF Administrator's Guide.

Related commands

To bind a certificate to a token, see RACDCERT BIND.
To list a token, see RACDCERT LISTTOKEN.

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

RACDCERT UNBIND(TOKEN(token-name)

{ [ ID(certificate-owner) | SITE | CERTAUTH ] LABEL('label-name')
| SEQNUM(sequence-number) }
)
[ FORCE ]

Note: Unless specified as a subkeyword of the UNBIND parameter, the ID(certificate-owner) | SITE | CERTAUTH parameter is ignored for the RACDCERT UNBIND 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.

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

Parameters

UNBIND(TOKEN(token-name) ID(certificate-owner) LABEL('label-name'))

UNBIND(TOKEN(token-name) SITE LABEL('label-name'))

UNBIND(TOKEN(token-name) CERTAUTH LABEL('label-name'))

UNBIND(TOKEN(token-name) SEQNUM(sequence-number))

You must uniquely identify the certificate to be removed in one of the following ways:

By its RACF label name (if defined to RACF), and optionally identify it as a user, SITE or CERTAUTH certificate. (The certificate must be defined to RACF when you specify the label name.)
By its sequence number within the token. (The certificate need not be defined to RACF when you specify the sequence number.)

TOKEN(token-name)

Specifies the name of the token from which the certificate is being removed. When specifying the UNBIND operand, you must specify the TOKEN operand.

ID(certificate-owner) | SITE | CERTAUTH

Specifies that the certificate to remove from the token 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.

LABEL('label-name')

Specifies the certificate to remove from the token. LABEL is mutually exclusive with SEQNUM.

SEQNUM(sequence-number)

Specifies the sequence number of the certificate to remove from the token. If the certificate (or its associated private key, if any) is not currently defined to RACF, you must also specify FORCE or else an error message is issued and the command ends. (This error prevents you from inadvertently deleting a certificate that is not defined to RACF.) SEQNUM is mutually exclusive with LABEL.

FORCE

Specifies that RACF should bypass some error checking and unconditionally perform the unbind operation.

If you do not specify FORCE, the following condition must be true or an error message is issued and the command ends:

The certificate (or its associated private key, if any) must be currently defined to RACF.

If you specify FORCE, this condition is not checked. If you specify FORCE and inadvertently specify a sequence number for a certificate not defined to RACF, the certificate (or its associated private key, if any) is deleted.

Examples

Example	Activity label	Description
1	Operation	User NETB0Y wants to remove a digital certificate labeled `My temp certificate` from the z/OS PKCS #11 token named `NETB0Y.TKN1`. The certificate does not currently reside in RACF.
	Known	User NETB0Y has CONTROL authority to the discrete profile named `USER.NETB0Y.TKN1` in the CRYPTOZ class. Using RACDCERT LISTTOKEN, user NETB0Y determined the sequence number of the certificate to be removed is `3`.
	Command	`RACDCERT UNBIND(TOKEN(NETB0Y.TKN1) SEQNUM(3)) FORCE`
	Output	None.