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.

(SPE2407)

EC for Venafi supports creating private keys on both TPP and the mainframe. 

• If you set Generate Key/CSR on Application to No, the key is generated on TPP.
• If you set Generate Key/CSR on Application to Yes, the key is generated on the mainframe.

Keys generated on the mainframe do not support adding more than one subject alternate name (SAN) in a certificate request. To add more than one SAN, you must generate the key on TPP.

EC for Venafi supports both RSA and ECC keys, so you must set the key type in Key Algorithm to either RSA or ECC. 

• If you choose an RSA key, you must also set the Key Strength (bits).
• If you choose an ECC key, you must also set the Elliptic Curve. 

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 and key rings

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.

• 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. If you don't specify a key ring name, the default certificate flag is ignored.

  Example

  LPAR2*[nokeyring]*Certificate Label*MTT

• If the certificate is loaded on multiple target environments, 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 the certificate owner and the key ring 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, use [nokeyring] in the first definition string if you want the certificate to be owned by one user but to be in the key rings of other users.

  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

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.