Using certificate discovery

EC for Venafi can find user and site certificates on any LPAR running an EC for Venafi agent. Certificate discovery is supported by all three major ESMs (RACF, Top Secret, and ACF2) and is performed on all configured LPARs.

Prerequisites

To implement certificate discovery, you must meet the following requirements.

TPP concepts

Be familiar with how certificate discovery works in TPP.
Know how to set up and run an onboard discovery job.
Understand how certificate placement works.

TPP configuration

Create a device object for the onboard discovery job that is configured with the details of your EC for Venafi gateway. For more information about the gateway, see Configuring-the-gateway.
Set a secondary credential if you are using AT-TLS on the EC for Venafi gateway and AT-TLS requires a client certificate. For more information, see the "Policy objects" section in Configuring-the-TPP-adaptable-driver.

Exceptions

During discovery, EC for Venafi agents retrieve user and site certificate details from the key rings in the external security manager (ESM) of their LPAR. The following certificate types are ignored:

CERTAUTH certificates—These are generally CA certificates that are not managed by TPP.
Certificates with labels that end in .GEN—These are byproducts of the way in which EC for Venafi generates private keys and Certificate Signing Requests (CSRs).
Certificates with labels that end in .NEW and .OLD

Naming

During discovery, TPP names certificate and application objects according to the following conventions:

Certificate object names are generated automatically by using the Common Name (CN) attribute in the associated certificate.
Application object names are generated by using the name or names of the LPARs on which the certificate is installed and the certificate label that is provided by EC for Venafi.

Key ring and LPAR ordering

Be aware of the following conventions when TPP creates application objects for certificates discovered by EC for Venafi:

For certificates that are connected to multiple key rings on the same LPAR, EC for Venafi records the key rings in alphabetical order.
For certificates that are installed on multiple LPARs, EC for Venafi records the LPARs in alphabetical order.
For certificates that are connected to multiple key rings on multiple LPARs, EC for Venafi groups all of the key rings for each LPAR together, lists the key rings for each LPAR in alphabetical order, and then lists the LPARs in alphabetical order.

Alphabetizing the LPARs might mean that when a certificate is renewed, TPP does not generate the new private key on the LPAR that you used previously. Normally, this is not an issue because you can transfer private keys between LPARs irrespective of the ESMs that you use. Inspect the target environment (the Endpoint field) of the application objects for newly discovered certificates and modify them if required. For more information, see Task 3 under "Certificate and Application object management" in Configuring-the-TPP-adaptable-driver.

Important

If you change the order of the key rings or LPARs in an application object and then run another discovery job, TPP might create a second application object for the certificate already associated with the modified application object.

Certificates on multiple LPARs

(SPE2407)

When EC for Venafi discovers a certificate that is present on multiple LPARs, it verifies that the certificate configuration is consistent across the LPARs. For example, a certificate cannot be a site certificate on some LPARs but not others.

If EC for Venafi discovers a certificate that is a personal certificate on each LPAR, it records the certificate owner and all connected key rings. If the certificate owner does not have the certificate connected to any of their key rings, EC for Venafi creates a [nokeyring] definition.
If EC for Venafi discovers a certificate that is a site certificate on each LPAR, it records the owner of each of the connected key rings and sets the Force Site Certificate option in TPP to Yes.
If EC for Venafi discovers a certificate that is a site certificate on some LPARs but not others, it records a warning in the TPP adaptable driver debug log (if enabled) and sets the Force Site Certificate option in TPP to Yes. It also records a message in the relevant EC for Venafi agent log.

Important

Before version 2.3 SPE2407, if EC for Venafi created a certificate that would be connected to multiple key rings, owned by different users, on the same LPAR, EC for Venafi automatically created the certificate as a site certificate. Now EC for Venafi only creates certificates as site certificates if the Force Site Certificate option is set to Yes.

ICSF

EC for Venafi verifies if a certificate’s private key is stored in ICSF. If it is, EC for Venafi indicates that TPP set the Generate and store key in ICSF instead of ESM option to Yes.

The Generate and store key in ICSF instead of ESM option applies to all LPARs on which a certificate is installed. If EC for Venafi finds a certificate on any LPAR in which the option is set to Yes, the option is set to Yes for all LPARs. If a certificate on one LPAR is set to Yes, and on a second LPAR it is set to No, the certificate on the second LPAR is reinstalled with the option set to Yes the next time you renew it.

If EC for Venafi discovers a configuration where a certificate stores its private key in ICSF on one LPAR but not on another LPAR, EC for Venafi records the affected LPARs, key rings, and certificate labels in the TPP adaptable driver debug log (if enabled). It also records a message in the relevant EC for Venafi agent log. For more information about the TPP adaptable driver debug log, see Task 7 under "Certificate and Application object management" in Configuring-the-TPP-adaptable-driver.