Steps for setting up PKI Services to generate keys for certificate requests

Perform the following steps to set up key generation for certificate requests.

1. If the ICSF token data set (TKDS) has not already been set up, ask the ICSF programmer to set it up. (For information about the TKDS, see z/OS Cryptographic Services ICSF Writing PKCS #11 Applications.) The TKDS must be set up before PKI Services starts, so if necessary stop and restart PKI Services after the TKDS is set up. (For information about stopping and restarting PKI Services, see Starting and stopping PKI Services.

   _______________________________________________________________

2. Edit the SAF section of the PKI Services configuration file, pkiserv.conf, and verify that the TokenName parameter is specified. If it is not, choose a name for the token in the TKDS that PKI Services uses for storing the key pairs that it generates, and set TokenName to the name you choose.
   Rules: A token name must follow these rules:

   • Up to 32 characters in length
   • Permitted characters are:
     • Alphanumeric
     • National: "@" (X'5B'), "#" (X'7B'), or "$" (X'7C')
     • Period: "." (X'4B')
   • The first character must be alphabetic or national
   • Lowercase letters can be used, but are folded to uppercase
   • The IBM1047 code page is assumed

   _______________________________________________________________

3. Edit the SAF section of the PKI Services configuration file, pkiserv.conf and set the SecureKey parameter to T if you want PKI Services to generate secure keys, or to F if you want PKI Services to generate clear keys.

   _______________________________________________________________

4. If you want to restrict the generation of clear keys, have the security administrator create a profile in the CRYPTOZ class to do so. For example, if you set TokenName to PKISRVD.PKITOKEN, to restrict PKI Services from generating clear keys the security administrator issues the command:

   RDEF CRYPTOZ CLEARKEY.PKISRVD.PKITOKEN UACC(NONE)

5. Edit the General section of the PKI Services configuration file, pkiserv.conf, and verify that the ReadyMessageForm parameter is specified. If it is not:
   • Copy the ready message form from the samples directory to the runtime directory. Follow the instructions in Steps for copying files.
   • Update the ReadyMessageForm parameter to specify the full path name or data set name of the ready message form.
   • Customize the ready message form. Follow the instructions in Customizing email notifications sent to users.

   _______________________________________________________________

6. Set up the email form that is sent if a user requests that PKI Services recover a certificate for which PKI Services generated the keys. The form contains a list of certificates that can be recovered. Edit the General section of the PKI Services configuration file, pkiserv.conf and verify that the RecoverForm parameter is specified. If it is not:
   • Copy the recovery message form from the samples directory to the runtime directory. Follow the instructions in Steps for copying files.
   • Update the RecoverForm parameter to specify the full path name or data set name of the recovery message form.
   • Customize the recovery message form. Follow the instructions in Customizing email notifications sent to users.

   _______________________________________________________________

7. If you want expired certificates whose keys were generated by PKI Services to be deleted from the ICL automatically after a certain time period, edit the ObjectStore section of the PKI Services configuration file, pkiserv.conf and update the RemoveExpiredCertsAndKeys parameter to specify the time period after which the expired certificates should be deleted.

   _______________________________________________________________

8. The RACF® administrator must give the PKI Services daemon the authorization it needs to use the PKCS #11 APIs. The following RACF commands set up the required authorization in the CRYPTOZ class. (By default the daemon user ID is PKISERVD, but you might be using a different user ID. Check the daemon variable in Table 1 if you are not sure what your daemon user ID is.)

   SETROPTS CLASSACT(CRYPTOZ) GENERIC(CRYPTOZ) RACLIST(CRYPTOZ)
   RDEFINE CRYPTOZ SO.daemon_id.* UACC(NONE)
   RDEFINE CRYPTOZ USER.daemon_id.* UACC(NONE)
   PERMIT SO.daemon_id.* CLASS(CRYPTOZ) ID(daemon_id) ACC(UPDATE)
   PERMIT USER.daemon_id.* CLASS(CRYPTOZ) ID(daemon_id) ACC(CONTROL)
   SETROPTS RACLIST(CRYPTOZ) REFRESH

   Note: These commands are included in the IKYSETUP REXX exec. If you have another reason to rerun IKYSETUP, you can update the exec to set up the daemon user ID's authorization in the CRYPTOZ class at the same time. If you do not have another reason to rerun IKYSETUP, the RACF administrator can issue the commands manually.

   _______________________________________________________________

9. (Optional) Because PKI Services stores certificates for which it generates the keys in the TKDS, it can recover those certificates from the TKDS. To recover a certificate, a user must provide the passphrase that was entered when the certificate was originally requested. If the user has forgotten the passphrase, you can use the PKI Services exit to allow the user to recover the passphrase by responding to security questions. For more information, see Scenario 4: Allow users to recover a PKI generated key certificate when the passphrase is lost. Decide whether you want to implement passphrase recovery, and if so, write exit code to implement the function.
10. (Optional) When PKI Services generates the keys for certificate requests, it returns both the certificate and the private key in PKCS#12 format when retrieved by the requester. By default, the PKCS#12 contains the CA certificate that signed the requested certificate. The contents of the PKCS#12 may be tailored to contain only the issued certificate with private key, the issued certificate with private key, and the CA certificate that signed the issued certificate, or the issued certificate with private key and the complete CA signing chain. Use the PKCS12Content keyword in the pkiserv.conf file to specify the PKCS#12 content. When PKCS12Content is set to either I or E, no further configuration is required. However, when PKCS12Content=C is set, if the PKI CA certificate is not a root CA (self-signed), each of the CA certificates in the signing chain must be connected to the PKI Services key ring with CERTAUTH usage. For example, If the PKI Services CA certificate is signed by a CERTAUTH certificate with a Label of "Dime-o-Cert Root CA", and the pkiserv.conf file has Keyring=PKISRVD/CAring in the [SAF] section, the following RACF command is issued to connect the root CA certificate to the PKI Services key ring:

    RACDCERT ID(PKISRVD) CONNECT(CERTAUTH LABEL('Dime-o-Cert Root CA') ring(CAring))