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 ringUSAGE 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 ringUSAGE 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. |