Using TPP certificates and application objects

Task 1: Certificate objects

Set the management type

For TPP to manage the installation of a certificate onto an application, you must set the certificate object’s management type to Provisioning.

Task 2: Application objects

Each certificate that is deployed on the mainframe requires an application object to define the target environments where the certificate will be used.

When you create an application object, the PowerShell Script field automatically displays the name of the PowerShell script that was defined in the parent Policy folder, for example, EC for Venafi SPExxxx. It is important that the name of the PowerShell script include the SPE version of EC for Venafi to make sure that you are using a version of the script that is compatible with the product.

If the application object does not reflect the correct PowerShell script name, the application object is either in the wrong location in the policy tree, or its parent Policy folder was not configured correctly.

Task 3: Configuring certificate endpoints

Define the certificate installation location in one of the following fields in Adaptable Settings for the application object:

• Endpoint(s)
• Certificate-only endpoint(s)

Endpoints (standard)

For each LPAR or group of LPARs where both the certificate and private key are required, enter the environment name, the key ring name, certificate label, and owner ID in the Endpoint(s) field, all separated by asterisks.

The environment name (LPAR2 in the example) can be an LPAR where an agent is located or an LPAR group name, both of which are defined in the gateway configuration.

• If the certificate is flagged as the default certificate in the key ring, add *D to the end of the definition string.

• To create a certificate that is not connected to a key ring, enter [nokeyring] in the definition string. The default certificate flag is ignored if the certificate is not connected to a key ring.

  Example

  LPAR2*[nokeyring]*Certificate Label*MTT

• If the certificate and private key are loaded on multiple endpoints (this can be both multiple key rings on the same LPAR and key rings on multiple LPARs), separate the definition strings with a semicolon and one or more spaces.

  Example

  LPAR1*Key Ring 1*Label 1*MTT; LPAR2*Key Ring 2*Label 2*MTT

(SPE2407)

The order of the defined target environments is very important.

• If you are installing a certificate on multiple LPARs, the first LPAR in the list is used to generate the private key.

• If you are connecting a certificate to multiple key rings on an LPAR, the definition string for the first key ring sets both the key ring owner and the certificate owner. 

  Example

  A certificate owned by USER1 is connected to key rings owned by USER1 and USER2:

  LPAR1*User1KeyRing*ManagedCertificate*USER1; LPAR1*User2KeyRing*ManagedCertificate*USER2

• If you are connecting a certificate to multiple key rings on an LPAR and want the certificate to be owned by one user but to be in the key rings of other users, enter [nokeyring] in the first definition string.

  Example

  A certificate owned by USER1 is connected only to key rings owned by USER2 and USER3:

  LPAR1*[nokeyring]*ManagedCertificate*USER1; LPAR1*User2KeyRing*ManagedCertificate*USER2; LPAR1*User3KeyRing*ManagedCertificate*USER3

Certificate-only endpoints

For each key ring where the certificate is installed with USAGE(CERTAUTH), enter the environment name, key ring name, certificate label, owner ID, and the word CERTAUTH into the Certificate-only endpoint(s) field, all separated by asterisks.

• The environment name (LPAR2 in the example) must be one of the LPARs where an agent is located. These are defined in the gateway configuration.
• You must include *CERTAUTH at the end of each endpoint definition. If you do not include *CERTAUTH, an endpoint intended to have a private key might accidentally be entered as a certificate-only endpoint, or the opposite might occur.
• EC for Venafi checks each LPAR that is referenced in an application object to verify whether all the endpoints are standard endpoints, all certificate-only endpoints, or some of each type:
  • If all of the endpoints are certificate-only, EC for Venafi does not load the private key into the ESM when it loads the certificate.
  • If some of the endpoints are standard endpoints and some are certificate-only, the private key must be present in the ESM for the standard endpoints.
  • If a certificate with standard endpoints is in a key ring with USAGE(CERTAUTH), the ESM itself prevents the application from making use of the private key.

Task 4: Adding a post-implementation script

If you specify a REXX script in Post-implementation script name, EC for Venafi runs the script after the certificate is successfully created.

Post-implementation scripts perform additional tasks on your site, for example:

• Issuing a command to refresh a started task running on the system
• Running a Write to Operator (WTO) macro that your site's automation product can pick up

For more information about how to create and use a post-implementation script, see Configuring the post implementation script.

Task 5: Generating keys in ICSF

If you set the Generate and store key in ICSF instead of ESM option to Yes, EC for Venafi generates and stores the private key in ICSF instead of in an ESM.

(SPE2404)

When you use the Generate and store key in ICSF instead of ESM option in TPP, EC for Venafi behaves in the following manner:

• If you create an application object and set the option to No, the key for the associated certificate is stored in the ESM.
• If you later modify the application object and change the option to Yes, the next time the certificate is renewed, the key is stored in ICSF.
• If you create an application object and set the option to Yes, the key for the associated certificate is stored in ICSF.
• If you later modify the application object and change the option to No, the next time the certificate is renewed, the key is still stored in ICSF. Use the following workaround to renew a certificate with a private key in ESM after the key was previously in ICSF:
  1. In TPP, set the Generate and store key in ICSF instead of ESM option to No.
  2. Manually delete the existing certificate from the ESM. (Do not delete the certificate or application object from TPP.)
  3. Renew the certificate.

Task 6: Site certificates

(SPE2407)
If you set the Force Site Certificate option to Yes, new certificates are created as site certificates instead of personal certificates. For more information about site certificates, see Key features.

Task 7: Debug logging

If you select the Enable Debug Logging option, the driver logs its operations to a file in the Logs directory in the TPP installation folder. The name of the log file is EC for Venafi_GUID where GUID is the unique hexadecimal identifier for the application object in TPP. This value is obtained from the application object’s Support tab after the object has been created.