RACDCERT BIND (Bind certificate to token)

Purpose

Use the RACDCERT BIND command to bind a digital certificate to a z/OS® PKCS #11 token.

Rule: The certificate must be added to the RACF® database by a RACDCERT ADD or RACDCERT GENCERT command prior to issuing the RACDCERT BIND command.

When a certificate is bound to a token, RACF creates the following objects in the token:

a certificate object
a public key object
a private key object, if the certificate has an associated private key and the BIND USAGE is PERSONAL.
If the private key is secure, it will already have a private key object in the token specified on GENCERT request. In this case, BIND will create a certificate object, a public key object, and, if the BIND USAGE is PERSONAL, will link the existing private key object to the certificate and public key objects.

Restrictions on the private key: The following restrictions apply to the private key of the certificate to be bound. Command processing stops and an error message is displayed.

The private key must not be stored in the ICSF PKA key data set (PKDS).
The private key must not be a DSA key longer than 1024 bits.

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 BIND 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 BIND command, you must have the following authorizations:

The SPECIAL attribute, or sufficient authority to the IRR.DIGTCERT.BIND resource in the FACILITY class based on the USAGE value, as shown in Table 1.
The SPECIAL attribute, or sufficient authority to the IRR.DIGTCERT.ADD resource in the FACILITY class based on the certificate owner.
When your installation controls access to ICSF services and the CSFSERV class is active, READ access to the CSF1GAV, CSF1SAV, CSF1TRC, and CSF1TRL resources in the CSFSERV class.
Sufficient authority to the appropriate resources in the CRYPTOZ class.
For details about CRYPTOZ and CSFSERV resources, see z/OS Cryptographic Services ICSF Administrator's Guide.

If you are not authorized by ICSF (through the CRYPTOZ class) to add the object to the specified token or not authorized by RACF (through the FACILITY class) to reference the specified RACF certificate, the command stops and an error message is displayed.

Table 1. Authority required for the RACDCERT BIND function
USAGE value	Your own certificate	Another user's certificate	SITE or CERTAUTH certificate
PERSONAL	Sufficient authority to CRYPTOZ resources and READ authority to IRR.DIGTCERT.BIND	Sufficient authority to CRYPTOZ resources and UPDATE authority to IRR.DIGTCERT.BIND	Sufficient authority to CRYPTOZ resources and CONTROL authority to IRR.DIGTCERT.BIND
SITE CERTAUTH	Sufficient authority to CRYPTOZ resources, CONTROL authority to IRR.DIGTCERT.ADD and READ authority to IRR.DIGTCERT.BIND	Sufficient authority to CRYPTOZ resources, CONTROL authority to IRR.DIGTCERT.ADD and UPDATE authority to IRR.DIGTCERT.BIND	Sufficient authority to CRYPTOZ resources and UPDATE authority to IRR.DIGTCERT.BIND

Related commands

To unbind a certificate from a token, see RACDCERT UNBIND.
To add a token, see RACDCERT ADDTOKEN.
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 BIND command is:


RACDCERT BIND([TOKEN(token-name)]
LABEL('label-name') [ID(certificate-owner) \| SITE \| CERTAUTH] [DEFAULT] [USAGE(PERSONAL \| SITE \| CERTAUTH)] )

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

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

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

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

You must uniquely identify both the token and the certificate to be bound.

TOKEN(token-name)

Specifies the name of the token to which the certificate is to be bound. If it is not specified, the token, in which the private key associated with the binding certificate resides, will be used.

If the certificate has an associated ECC private key, the ICSF subsystem must be operational and configured for PKCS #11 operations.

ID(certificate-owner) | SITE | CERTAUTH

Specifies that the certificate being bound to the token is either a user certificate associated with the specified user ID, a site certificate, or a certificate-authority certificate. If the ID, SITE, and CERTAUTH keywords are omitted, 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 being bound to the token. For RACDCERT BIND, you must specify the LABEL operand.

DEFAULT

Specifies that the certificate is the default certificate for the token. Only one certificate within the token is the default certificate. If a default certificate already exists, its DEFAULT status is removed, and the specified certificate becomes the default certificate.

You must specify the DEFAULT keyword when you want the specified certificate to be the default certificate for this token.

To remove the DEFAULT status of a certificate without defining another certificate as the default certificate, reissue the RACDCERT BIND command for the certificate and omit the DEFAULT keyword.

USAGE(PERSONAL | SITE | CERTAUTH)

Specifies how this certificate is used within the specified token. If no usage is specified, it defaults to the usage of the certificate being bound.

Specify the USAGE keyword to alter the trust policy of the certificate for a specific token. For example, if you operate your own certificate authority, your certificate server application has its own certificate. Because the certificate represents your certificate authority, it is defined as CERTAUTH, which sets its default usage for all applications and users. Your certificate server application requires use of the certificate's private key for signing purposes but the default usage of CERTAUTH does not allow this use. To allow it, specify USAGE(PERSONAL) when you bind this certificate to the token of the certificate server application. This allows you to alter the trust policy for this token only without affecting the default usage for all other applications and users.

Important: Carefully control use of the USAGE keyword. RACDCERT processing ensures that the command issuer is authorized to define SITE or CERTAUTH certificates and cannot bypass the installation security policy using the USAGE keyword.

See Table 1 for authorization requirements for users without the SPECIAL attribute to allow them to bind a certificate to a token with the PERSONAL, SITE, or CERTAUTH usage.

Examples


Example 1	Operation	User SECADM wants to bind an existing root CA certificate to two existing tokens.
	Known	User SECADM has the SPECIAL attribute. The root CA certificate is installed under CERTAUTH with the label `Local Root CA for Servers`. The following tokens are already defined to RACF: `ftpsrv.ftp.server.pkcs11.token` `websrv.web.server.pkcs11.token`
	Commands	`RACDCERT BIND(CERTAUTH LABEL('Local Root CA for Servers') TOKEN(ftpsrv.ftp.server.pkcs11.token)) RACDCERT BIND(CERTAUTH LABEL('Local Root CA for Servers') TOKEN(websrv.web.server.pkcs11.token))`
	Output	None.

Example 2	Operation	User SECADM wants to bind end-entity certificates to their respective tokens and define each certificate as the default in its token.
	Known	User SECADM has the SPECIAL attribute. The following tokens are already defined to RACF: `ftpsrv.ftp.server.pkcs11.token` `websrv.web.server.pkcs11.token` An end-entity certificate and private key labeled `FTP key` is already defined to RACF and installed under the user ID FTPSRV. An end-entity certificate and private key labeled `Web key` is already defined to RACF and installed under the user ID WEBSRV. Both end-entity certificates are signed by the existing root CA certificate labeled `Local Root CA for Servers`.
	Commands	`RACDCERT BIND(ID(FTPSRV) LABEL('FTP key') DEFAULT TOKEN(ftpsrv.ftp.server.pkcs11.token)) RACDCERT BIND(ID(WEBSRV) LABEL('Web key') DEFAULT TOKEN(websrv.web.server.pkcs11.token))`
	Output	None.