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
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 |
- 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
- 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
- Sufficient authority to the appropriate resources in the RDATALIB class, as shown in Table 3, if Granular Authority Checking has been enabled by defining the IRR.RACDCERT.GRANULAR resource in the RDATALIB class.
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.
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 |
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 |
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 |
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 |
READ access to the resource based on cert owner and cert label, ring owner and ring name * | Purpose |
---|---|
IRR.DIGTCERT.<cert owner>.<cert label>.LST.CONNECT |
Connect a certificate with specified <cert label> owned by <cert owner> to a key ring with specified <ring name> owned by <ring owner> with no USAGE keyword specified. |
IRR.DIGTCERT.<cert owner>.<cert label>.UPD.CONNECT |
Connect a certificate with specified <cert label> owned by <cert owner> to a key ring with specified <ring name> owned by <ring owner> with USAGE keyword specified. |
See the USAGE subkeyword 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.
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 ] |
|
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 preceding, 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 | Activity label | Description |
---|---|---|
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 |
|
|
Output | None. |