Creating a CAPI application object

This section describes the configuration settings needed to enable Trust Protection Platform to install an SSL certificate key pair into the CAPI store of a Microsoft Windows host.

BEST PRACTICE Consider managing object settings using a policy. For more information, see Managing applications using policies.

DID YOU KNOW? When you add an installation to a certificate, you'll have the option of defining (and editing) this object during that process, which means that you don't have to log in to Policy Tree as the following procedure describes. And because the settings are the same, you can use this topic for information about each setting.

For more information, see Creating a certificate installation.

To create and configure a CAPI application object

From the TLS Protect menu bar, click Policy tree.
In the Policy tree, select the device object to which you want to add the new application object, and then click Add > Application, and then select CAPI.
When the new application object page appears, then under Status, clear the Processing Disabled checkbox.

When checked, this option disables provisioning of the certificates installed on the current application. This means that Trust Protection Platform does not attempt to install, renew, process, or validate certificates on the application.
(Optional) In the Device Certificate box, click to select and associate a certificate with the new application.

NOTE If you don't have a certificate ready, you can do this later or you can do it on the certificate's Association tab.

To associate a certificate with the current application, you must have write permissions to the application object and either write or associate permissions to the certificate object.

For detailed information on associating a certificate with an application, see Associating a certificate with an application object.
Under General, do the following:
1. In the Application Name field, type a name for the new application.
2. (Optional) In the Description field, type a description for the purpose of the application.
  
  A strong description can help to provide context for other administrators who might need to manage the new application.
3. In the Contacts field, select user or group identities you want assigned to this application object (or choose the Use policy value to configure contacts using a policy).
  
  Default system notifications are sent to the contact identities. The default contact is the master administrator.
  
  TIP If the Identity Selector dialog is not populated when it first opens, enter a search query to retrieve the Identity list. The administration console does not automatically display external users and groups. You must first enter a search string so Trust Protection Platform can query the external Identity store, then return the list of requested users or groups. If you want to display all user or group entries, enter the wildcard character (*).
  
  Press Shift+click to select multiple, contiguous users and groups. Press Ctrl+click to select multiple, discontiguous users and groups.
4. In the Approvers field, select user or group Identities you want to assign to approve workflows (certificate approval or injection command) for the new application.
  
  The default approver is the master administrator. For more information on defining workflow objects, see Implementing certificate workflow management.
5. (Conditional) If your application (or certificate) object is affected by a defined workflow and you want users to use a console other than Policy Tree, click Managed By and select which administration console to use as part of the workflow.
  
  You only need to configure this if you are using workflows and expect users to perform a task using a particular administration console. The default setting is Policy Tree.
  
  For more information, see Specify folders and certificates to be managed by TLS Protect .
Under Application Information, do the following:
1. Click next to Application Credential to browse for the credential object that you want to use to authenticate with the application.
  
  DID YOU KNOW? Credential objects store the credentials Trust Protection Platform uses to authenticate with devices, applications, and CAs. The stored credential might be a user name or private key credential; some drivers—such as F5, which is not SSH-based—can only use the user name credential for authentication.
  
  NOTE The user account you select must have Read and Write access to the Temporary, Private Key, and Certificate directories.
  
  For more information, see Working with system credentials.
  
  DID YOU KNOW? The Connection Method is the protocol that Trust Protection Platform uses to connect to the server and manage the certificates installed on that server. In an application object's settings, this field is typically read-only.
2. In the WinRM Port, specify the port number that Trust Protection Platform should use to communicate with CAPI devices.
  
  The default WinRM ports assignments are port 5985 and 5986 for HTTP and HTTPS, respectively.

Under Remote Generation Settings, click the Private Key Location list and select where you want remotely generated key pairs to be created:

TIP The Thales SafeNet Luna SA HSM and Entrust nShield HSM settings are not visible if you have not activated Advanced Key Protect. For more information, see Enabling Venafi Advanced Key Protect.
- Device: Select this option to generate key pairs on the device.
  
  This is the default setting.
- Thales SafeNet Luna SA HSM: Select this option to generate key pairs on a Thales SafeNet Luna SA HSM.
  - In the Key Label field (that appears only after you select Thales SafeNet Luna SA HSM), type the label that you want used for keys created by the CAPI driver in your HSM.
    
    This option makes it easier for you to identify which certificates correspond to the newly generated keys. If you leave this field empty, Windows automatically generates a unique name whenever a new key pair is created. Alternatively, you could choose to change the key label manually before renewing the certificate.
    
    DID YOU KNOW? Trust Protection Platform uses the label you specify each time that it provisions the certificate. Because Microsoft Windows allows only one instance of a particular key label, you must set Reuse Private Key for Service Generated CSRs to Yes on the certificate's policy, which prevents a possible error the first time the certificate is renewed. For more information, see Policy object certificate settings and Setting policy on a folder.
- Entrust nShield HSM: Select this option to generate key pairs on an Entrust nShield HSM using Module protection mode.

Refer to the following table to complete the remaining settings:

CAPI Settings

Field	Policy	Description
Friendly Name	No	The friendly name that identifies the certificate in the Windows CAPI store (required). Windows does not require the Friendly Name to be unique. If a name collision is encountered during validation or extraction, Trust Protection Platform uses the most recently issued certificate. NOTE When certificates are discovered by the Server Agent, the agent captures and sends the certificate label to Trust Protection Platform using the existing friendly name JSON object property. Trust Protection Platform then sets the certificate label value when it creates the new application object. DID YOU KNOW? Depending on the trust store, this setting goes by different names. For example, GSK refers to this setting as the Certificate Label, JKS refers to it as the Certificate Alias, and CAPI and PKCS#12 refer to it as the Friendly Name.
Exportable	Yes	Controls whether the private key installed by Trust Protection Platform is exportable from the CAPI store. NOTE When configuring CAPI for use with remote generation using an HSM and you have Generate Key/CSR on Application set to Yes, Private Key Location set to Thales SafeNet Luna SA HSM, and Reuse Private Key for Service Generated CSRs set to Yes), then make sure that you set Exportable to No.
Private Key Trustee	Yes	(Optional) A Windows identity that is granted read access to the private key in the CAPI store. When needed this is often the identity that the IIS Application Pool is running under. No special permissions are granted to the private key when left blank.

IIS Settings

Field	Policy	Description
Update IIS	Yes	Controls whether Trust Protection Platform will update IIS to use the installed certificate it just installed.
Web Site Name	Yes	The unique name of the IIS web site (Required if Update IIS is Yes).
Binding IP Address	No	The IP address for which the certificate will be bound to the IIS web site. If not specified the binding will be created for * which also appears as 'All Unassigned' in the Internet Information Services (IIS) Manager.
Binding Port	No	The port for which the certificate will be bound to the IIS web site (default is 443).
Binding Host Name	No	(Optional)Used to specify the TLS server name that IIS uses to determine which web site and certificate to present to server name indication (SNI)-enabled web clients. This field applies only when you are provisioning to IIS 8.0, IIS 8.5, and IIS 10. This is because SNI (which allows binding SSL to host names rather than IP addresses) was added with the release of IIS 8.0. If Trust Protection Platform attempts to provision to a target device running an earlier version of IIS, and you have specified a Binding Host Name value, this setting is simply ignored.
Create Binding	Yes	Controls whether Trust Protection Platform creates a binding for the web site if one does not already exist.

When you are finished, click Save.

For additional HSM configuration information, see Managing applications using HSM-protected keys and Venafi Advanced Key Protect and Configuring HSM-based remote key generation.

What's next?

After you've created an application object, here are other things you can do to manage the new application:

On the application's Settings sub-tab:
- Click to push a certificate to its associated application.
  
  For more information, see Pushing a certificate and private key to an application .
- Click Reset to stop processing the application and reset the status and stage.
- Click to reattempt installation of the certificate to its associated application, .
- Click Validate Now to validate the applications associated certificate.
  
  Validation requests are placed into a queue. When your validation runs, the application and its associated certificate are scanned according to the settings configured in the application object’s Validation tab.
  
  For more information, see About certificate and application validation.
On the application object's Validation tab, you can configure validation settings for the application object.
On an object's General tab:
- Click the Log sub-tab to view any events that are triggered by the template object.
- Click the Permissions sub-tab to configure the users or groups to whom you want to grant permissions to the new object. For more information, see Permissions overview.