RACDCERT CONNECT (Connect a certificate to key ring)

Purpose

Use the RACDCERT CONNECT command to add a digital certificate to a key ring.

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 CONNECT 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 CONNECT command, you must have the SPECIAL attribute or sufficient authority to the following resources in the FACILITY class, based on the certificate owner, key ring owner, and the USAGE value:

IRR.DIGTCERT.CONNECT
IRR.DIGTCERT.ADD

The USAGE keyword allows a certificate to be connected to a ring and used in a manner that differs from the certificate's original use. For example, by changing the USAGE value, a certificate defined as a user certificate might be used as a certificate-authority certificate.

The USAGE keyword is powerful, and must be controlled. The rules for connection are shown in Table 1, which shows the access control checks that are performed when connecting to your own key ring, and Table 2, which shows the access control checks that are performed when connecting to another user's key ring.

Table 1. Authority required for the RACDCERT CONNECT function - Connecting to your own key ring
USAGE value	Your own certificate	Another user's certificate	SITE or CERTAUTH certificate
PERSONAL	READ authority to IRR.DIGTCERT.CONNECT	UPDATE authority to IRR.DIGTCERT.CONNECT	CONTROL authority to IRR.DIGTCERT.CONNECT
SITE CERTAUTH	CONTROL authority to IRR.DIGTCERT.ADD and READ authority to IRR.DIGTCERT.CONNECT	CONTROL authority to IRR.DIGTCERT.ADD and UPDATE authority to IRR.DIGTCERT.CONNECT	UPDATE authority to IRR.DIGTCERT.CONNECT

Table 2. Authority required for the RACDCERT CONNECT function - Connecting to another user's key ring
USAGE value	Your own certificate	Another user's certificate	SITE or CERTAUTH certificate
PERSONAL	CONTROL authority to IRR.DIGTCERT.CONNECT	CONTROL authority to IRR.DIGTCERT.CONNECT	CONTROL authority to IRR.DIGTCERT.CONNECT
SITE CERTAUTH	CONTROL authority to IRR.DIGTCERT.ADD and CONTROL authority to IRR.DIGTCERT.CONNECT	CONTROL authority to IRR.DIGTCERT.ADD and CONTROL authority to IRR.DIGTCERT.CONNECT	CONTROL authority to IRR.DIGTCERT.CONNECT

See the USAGE subkeyword below for additional information on the authority required to change a certificate's usage.

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

To add a key ring, see RACDCERT ADDRING.
To remove a certificate from a key ring, see RACDCERT REMOVE.
To list a key ring, see RACDCERT LISTRING.

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


RACDCERT CONNECT([ID(certificate-owner) \| SITE \| CERTAUTH]
LABEL('label-name') RING(ring-name) [DEFAULT] [USAGE(PERSONAL \| SITE \| CERTAUTH)] ) [ID(ring-owner)]

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

CONNECT(ID(certificate-owner) LABEL('label-name') RING(ring-name))

CONNECT(SITE LABEL('label-name') RING(ring-name))

CONNECT(CERTAUTH LABEL('label-name') RING(ring-name))

Specifies the digital certificate to be added to the key ring. The specified certificate must be added to the RACF database by a RACDCERT ADD or RACDCERT GENCERT command prior to issuing the CONNECT command.

ID(certificate-owner) indicates that the certificate being connected is a user certificate, and certificate-owner is the user ID associated with this certificate. SITE indicates that the certificate being connected is a site certificate, and CERTAUTH indicates that it is a certificate authority certificate. If ID, SITE or CERTAUTH are not specified, ID(certificate-owner) defaults to the key ring owner as specified or defaulted by the ID(ring-owner) keyword.

LABEL('label-name')

Specifies the certificate that is being connected to the key ring. You must specify a label.

RING(ring-name)

Specifies the key ring to which this certificate is being connected. You must specify a ring name. Note: The key ring belongs to the ID specified or defaulted by the ID(ring-owner) keyword.

ID(ring-owner)

Specifies the user ID of the key ring owner. (Only a user ID can have a key ring.) If not specified, the key ring owner defaults to the command issuer's user ID.

DEFAULT

Specifies that the certificate is the default certificate for the ring. Only one certificate within the key ring can be the default certificate. If a default certificate already exists, its DEFAULT status is removed, and the specified certificate becomes the default certificate. If you want the specified certificate to be the default, DEFAULT must be explicitly specified.

If you have a key ring with a default certificate and you want to remove the default status of the certificate without defining another certificate as the default certificate, CONNECT the certificate again without specifying the DEFAULT keyword.

USAGE(PERSONAL | SITE | CERTAUTH)

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

The USAGE keyword allows the altering of the trust policy within the confines of a specific key ring. For example, if you are operating your own certificate authority, your certificate server application would have its own certificate. Because the certificate does represent a certificate authority, it should be installed under CERTAUTH, thus setting its default usage for all other applications and users. However, your certificate server application would need to use the certificate's private key for signing. The default usage of CERTAUTH does not allow this. So, for the certificate server application's key ring only, the certificate should be connected with USAGE(PERSONAL). Note, in addition to the above, the user ID assigned to your certificate server application needs to be granted permission to operate as a certificate authority. This is done by giving the user ID CONTROL access to FACILITY class resource IRR.DIGTCERT.GENCERT.

For the sake of consistency, other certificate and USAGE variations are supported. However, there is currently no practical application for them.

When using the USAGE keyword to change the usage of a certificate, such as is done when a PERSONAL certificate is being used as a SITE or CERTAUTH certificate, RACDCERT must ensure that you have the ability to define a SITE or CERTAUTH certificate by authenticating that the command issuer has CONTROL authority to the resource IRR.DIGTCERT.ADD in the FACILITY class. This ensures that a user cannot bypass the installation security policy through the use of USAGE.

Examples


Example 1	Operation	User RACFADM wants to connect an existing SITE certificate labeled `Shared Server` to the `RING01` key ring of server INVSERV. The certificate will be added to the key ring as the default certificate.
	Known	User RACFADM has SPECIAL authority.
	Command	`RACDCERT ID(INVSERV) CONNECT(SITE LABEL(’Shared Server’) RING(RING01) USAGE(PERSONAL) DEFAULT)`
	Output	None.