Steps for setting up PKI Services to encrypt returned private keys with certificates in a key ring

For PKI Services to encrypt private keys using certificates in a key ring, you must set up a key ring containing a digital certificate for each recipient.

Before you begin

You need to have RACF® SPECIAL authorization, or sufficient authority to the following resources in the FACILITY class:
- IRR.DIGTCERT.ADDRING
- IRR.DIGTCERT.ADD
- IRR.DIGTCERT.CONNECT
You must have a certificate for each certificate recipient, in a data set.

Note: This example assumes that you are using certificates that were created somewhere else. Alternatively, you could create the certificates using the RACF command RACDCERT GENCERT. If you take this approach, you need authorization to the resource IRR.DIGTCERT.GENCERT in the FACILITY class.

Procedure

Set the HTTP Server environment variable _PKISERV_CMP_KEYRING:
```
_PKISERV_CMP_KEYRING_domain_name=RACF_userID/ring_name
```
RACF_userID can be any RACF user ID; for example, the PKI Services daemon user ID, or the CMP requester user ID. ring_name is a name that you choose, and use when you create the key ring.
_______________________________________________________________
Create a RACF key ring, specifying the RACF user ID and the ring name that you specified in step 1.
```
RACDCERT ID(RACF_userID) ADDRING(ring_name)
```
_______________________________________________________________
Add certificates for each recipient to the RACF database, using the RACF user ID that you specified in step 1.
```
RACDCERT ID(RACF_userID) ADD(dataset_1) WITHLABEL('label_1')TRUST
RACDCERT ID(RACF_userID) ADD(dataset_2) WITHLABEL('label_2')TRUST⋮
RACDCERT ID(RACF_userID) ADD(dataset_n) WITHLABEL('label_n')TRUST
```
dataset_n is the name of the data set containing the certificate for recipient n. label_n is the label to be associated with the certificate for recipient n.
_______________________________________________________________
Add the digital certificates to the key ring that you created in step 2.
```
RACDCERT ID(RACF_userID) CONNECT(LABEL('label_1') RING(ring_name))
RACDCERT ID(RACF_userID) CONNECT(LABEL('label_2') RING(ring_name))
⋮
RACDCERT ID(RACF_userID) CONNECT(LABEL('label_n') RING(ring_name))
```
label_n is the label you associated with the certificate for recipient n in step 3.
_______________________________________________________________
Authorize the PKI Services CMP CGI program to access the key ring. This program runs with the RACF user ID that the client-supplied certificate maps to, so you must give that RACF user ID access to the key ring. You can use one of two methods:
- (Preferred) Define a profile in the RDATALIB class for the key ring and give each CMP client user ID READ access:
```
RDEFINE RDATALIB ring_owner.ring_name.LST UACC(NONE)
PERMIT ring_owner.ring_name.LST CLASS(RDATALIB) ID(client_user_id) ACCESS(READ)
```
  ring_owner is the RACF user ID you that specified in step 2, and ring_name is the ring name that you specified.
- (Alternative) Define a profile in the FACILITY class for IRR.DIGTCERT.LISTRING. Give the ring owner READ access and the client user IDs UPDATE access:
```
RDEFINE FACILITY IRR.DIGTCERT.LISTRING UACC(NONE)
PERMIT IRR.DIGTCERT.LISTRING ID(ring_owner) ACCESS(READ)
PERMIT IRR.DIGTCERT.LISTRING ID(client_user_id) ACCESS(UPDATE)
```
_______________________________________________________________
If either the DIGTCERT or DIGTRING class is RACLISTed, refresh the RACLISTed classes to activate your changes.
```
SETROPTS RACLIST(DIGTCERT, DIGTRING) REFRESH 
```
_______________________________________________________________

Results

When you are done, you have set up PKI Services to encrypt returned private keys with certificates in a RACF key ring.