Configuring the TPP adaptable driver

Policy objects

You must create a Policy folder and set the PowerShell script property to EC for Venafi.

If you have configured AT-TLS on the BMC AMI Enterprise Connector for Venafi gateway, and AT-TLS is configured to require a client certificate, you must create a certificate credential containing the relevant certificate and private key. You must choose this credential in the Secondary Credential field.

Set the port on which the gateway is listening in the Port field.

Device objects

Only one Device object is required per gateway, irrespective of how many certificates are being managed.

TPP insists on a user name Credential object to authenticate to devices. However, EC for Venafi does not need one. Instead, create a place holder user name object with any user name and password. Record it in the Description field for the credential that EC for Venafi uses.

Create the Device object inside the policy folder that you created in the previous section. In the Hostname/Address field, enter either http://gateway or https://gateway, where gateway is the host name or IP address where the gateway is listening. Do not add any trailing slash or port number.

In the Device Credential field, select the place holder credential.

Workflows

EC for Venafi splits the installation of a certificate into two stages to allow operations to be paused until the certificate owner is ready for a new certificate to be made live. To achieve this, you must create a workflow in TPP and apply it to the application objects.

Task 1: Creating a workflow reason code

For Code, enter an unused value. We recommend using 803, because this corresponds to the TPP Workflow stage where the workflow takes control.

For Name, enter EC for Venafi Authorization.

For Description, enter the following text:

Task 2: Creating a workflow object

If you don't already have a defined location in your policy tree where workflow objects are created, We recommend creating the workflow object alongside your device objects.

In the appropriate location, create a Standard Workflow object with the following details:

• Name—EC for Venafi Pause before certificate activation
• If Stage is—803
• If Application or Trust Store is—Adaptable App
• Inject Commands—No
• Request Approval—Yes
• Approval Reason Code—EC for Venafi Authorization

Configure the Request Approval From and Specified Approver(s) fields according to your own requirements and conventions.

Task 3: Assigning the workflow object

Add the workflow object created in the previous step to the Applied Workflows list in one of the policy folders that is a parent of the device object. We recommend that you apply this workflow object in the same policy folder in which the EC for Venafi adaptable application is configured.

Notifications

The workflow that you created causes TPP to pause processing until the certificate owner is ready for the certificate to be made live. You must create a customized TPP notification to tell certificate owners when a new certificate is ready.

Task 1: Creating a notification channel

Create a new SMTP channel. Configure this channel as required for your environment except for the following options:

• Recipient(s)—$IdentityEmail[$Event.Text1$]$
• Message Subject—Certificate for application $CN[$Event.Component$]$ is ready to be made live

• Message Body—

  The certificate for the following environment(s) has been loaded but requires your approval to be made live:
   
  $Policy[$Event.Component$,"Text Field 1"]$ 

  To act on this request, visit: https://$If[$Policy[$Event.Component$,Managed By]$, Aperture, $ApertureFQDN$/aperture/workflow/$GUID[$Event.Component$]$/approve, 
  $WebAdminFQDN$/vedadmin/Default.aspx?w=$ENCODE[URL,$CN[$Event.Text2$]$]$]$
   
  If you need assistance, contact your Administrator.
   
  When approving this change, please ensure that you add the change ID in the "Comments" section of the approval form.
   
  This email is being sent to you by $ProductName$ because you are named as an approver for this certificate or application: $Event.Component$

  Depending on your email configuration, you might also need to use the TPP Windows Administration Console to configure an HTML version of this notification.

Task 2: Creating a notification rule

Create a new notification under Notification Rules with the following settings:

Set the Target Channel to the notification channel that you created previously.

Certificate and Application object management

Perform the following steps to manage the TPP certificate and application objects.

Task 1: Certificate objects

As with any certificate where TPP manages the installation of the certificate onto an application, you must set the certificate object’s Management Type to Provisioning.

EC for Venafi manages the creation of the private key on the ESM, so you must set CSR Generation to Service Generated CSR, and set Generate Key/CSR on Application to Yes.

• EC for Venafi does not support adding more than one subject alternate name (SAN) in a certificate request.
• EC for Venafi does not impose any other requirements on certificate object parameters.

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 must show EC for Venafi. If it does not, then the application object is either in the wrong location in the policy tree or the parent Policy folder has not been configured correctly.

Task 3: Configuring target environments

You define the target environments in the Endpoint(s) field. For each target environment, enter the environment name (as defined in the gateway configuration), the key ring name, certificate label, and owner ID, all separated by asterisks. For example:

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

If the certificate is loaded on multiple target environments, separate the definition strings with a semicolon and one or more spaces. For example:

Task 4: Adding a post-implementation script

(SPE2307) 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 ESM.

Task 6: Site certificates

(SPE2307) If you set the Force Site Certificate option to Yes, new certificates are created as site certificates, which can be used by keyrings that are not managed by EC for Venafi. 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.