Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an...

101
Entrust Connector (eConnector) For Venafi Trust Protection Platform Installation and Configuration Guide Version 1.0.5 DATE: 17 November 2017 VERSION: 1.0.5 Copyright 2017. All rights reserved

Transcript of Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an...

Page 1: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

Entrust Connector (eConnector)

For

Venafi Trust Protection Platform

Installation and Configuration Guide

Version 1.0.5

DATE: 17 November 2017

VERSION: 1.0.5

Copyright 2017. All rights reserved

Page 2: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

Table of Contents

1 Entrust Connector (Econnector) Overview ........................................................................................... 3

2 Prerequisites And Requirements ........................................................................................................... 6

2.1 Econnector Prerequisites ............................................................................................................... 6

2.1.1 Create Entrust Security Manager Role .................................................................................. 6

2.1.2 Create Entrust Security Manager Server Logon Policy ...................................................... 10

2.1.3 Create Or Identify A Windows Account For The Powershell Client ................................. 11

2.2 System Prerequisites ................................................................................................................... 11

3 Installation – JAVA, Apache Tomcat, IIS Webserver ........................................................................ 12

3.1 Download JAVA JRE ................................................................................................................. 12

3.1.1 Setting The PATH Environment Variable .......................................................................... 12

3.2 Java JCE For Java JRE................................................................................................................ 13

3.2.1 Apply Java JCE Files Manually .......................................................................................... 13

3.3 Install 64-Bit Apache Tomcat As A Windows Service .............................................................. 13

3.3.1 Setting Environment Variables ........................................................................................... 13

3.3.2 Install Apache Tomcat As A Windows Service .................................................................. 14

3.4 Download Apache Tomcat Connector ........................................................................................ 15

3.5 Add IIS Webserver Role And Features ....................................................................................... 15

3.5.1 Install The Web Server (IIS) Role ...................................................................................... 15

3.5.2 Delete Default Web Site ..................................................................................................... 21

4 Installation – Econnector .................................................................................................................... 22

4.1 Opening And Preparing The Installation Package ...................................................................... 22

4.2 Running The Installer ................................................................................................................. 23

4.2.1 Run The Script .................................................................................................................... 23

4.2.2 License Agreement ............................................................................................................. 24

4.2.3 Java JCE .............................................................................................................................. 26

4.2.4 Econnector Native Library .................................................................................................. 27

4.2.5 Apache Tomcat Connector .................................................................................................. 28

4.2.6 Windows IIS Features ......................................................................................................... 30

4.2.7 Create An Econnector Instance ........................................................................................... 31

4.2.8 Configure Instance URL ..................................................................................................... 32

4.2.9 Configure Instance Logging ................................................................................................ 33

4.2.10 Configure Entrust Administrator RA Credential ................................................................ 34

Page 3: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

1

4.2.11 Generate User – Create EPF Locally .................................................................................. 35

4.2.12 Generate User – On HSM ................................................................................................... 38

4.2.13 Create UAL For RA Identity With EPF .............................................................................. 40

4.2.14 Verify The RA Identity With EPF And UAL ..................................................................... 43

4.2.15 Configure Econnector Instance Profiles .............................................................................. 45

4.2.16 Add A Profile ...................................................................................................................... 45

4.2.17 Edit A Profile ...................................................................................................................... 47

4.2.18 Remove A Profile................................................................................................................ 48

4.2.19 Save The Econnector Instance Settings .............................................................................. 50

4.2.20 Complete IIS Configuration ................................................................................................ 50

4.2.21 Setting The Website SSL/TLS Certificate .......................................................................... 52

4.2.22 Create An HTTPS Binding ................................................................................................. 58

4.2.23 Complete Website Configuration ........................................................................................ 59

4.2.24 Manage Client Authentication (Cauth) Mappings .............................................................. 62

4.2.25 Create Certificate For Mapping .......................................................................................... 63

4.2.26 Additional Options For Choosing The Client Authentication Certificate ........................... 67

4.2.27 Enter The Windows User Information ................................................................................ 71

4.2.28 Verify And Add The New Mapping ................................................................................... 72

4.2.29 Editing Mappings ................................................................................................................ 72

4.2.30 Remove Mapping ................................................................................................................ 74

4.2.31 Complete Website Client Authentication Configuration .................................................... 75

4.3 Complete Installation .................................................................................................................. 77

5 Venafi Configuration .......................................................................................................................... 79

5.1.1 Create A Venafi Custom Field ............................................................................................ 79

5.1.2 Create The Venafi User Name Credential .......................................................................... 80

5.1.3 Create The Venafi Adaptable CA Template ....................................................................... 82

6 Post Econnector Configuration (Optional).......................................................................................... 83

6.1 Post Installation Configuration Steps .......................................................................................... 83

6.1.1 Perform Post Installation Configuration Of The Econnector (Optional) ............................ 83

APPENDIX A – Certificate Stores ............................................................................................................. 85

6.2 Econnector Gateway Server ........................................................................................................ 85

6.2.1 IIS Binding .......................................................................................................................... 85

6.3 Local Computer Certificate Store ............................................................................................... 85

6.3.1 Personal Store ..................................................................................................................... 85

Page 4: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

2

6.3.2 Trusted Root Certificate Authorities Store ......................................................................... 85

6.4 Venafi TPP Server(S) ................................................................................................................. 86

6.4.1 Local Computer Store ......................................................................................................... 86

APPENDIX B – Add A New Econnector ................................................................................................... 87

APPENDIX C – Edit An Econnector ......................................................................................................... 88

APPENDIX E – Updating The Econnector Instance Profiles .................................................................... 92

APPENDIX F – Updating The Mapping .................................................................................................... 95

APPENDIX G – Remove The Mapping ..................................................................................................... 96

APPENDIX H – Upgrading An Existing Installation ................................................................................. 97

Page 5: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

3

1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW

The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager

based Certification Authorities (CA). It is composed of two parts, a PowerShell script which is run by the

Venafi application and a web service which performs the CA management functions requested by the

Venafi application. Additionally, multiple eConnector web service instances can be run. Each Entrust

Security Manager CA will use a distinctive Entrust Adaptable CA, subsequently having uniquely

configured entrust.ini, Entrust Administrator EPF, and profiles.

eConnector can be set up in two basic architectural models: gateway or co-hosted. In the gateway

architecture model (see Figure 1), the eConnector components reside on a separate server, apart from the

Venafi servers. In the co-hosted model, the eConnector components are installed on the Venafi servers

that will be configured to communicate with the Entrust Security Manager CA.

Figure 1 – eConnector Gateway Configuration

Page 6: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

4

Figure 2 – eConnector Co-hosted Architecture – Single Server Configuration

Figure 3 – eConnector Solution Components

Figure 3 provides an overview of the main elements of the eConnector and the Venafi Adaptable CA

solution. In addition to the eConnector components, specific configurations must be set within Venafi in

order to leverage the Adaptable CA driver. These configurations include creation of a Venafi Username

Credential and creation of a Custom Field that will contain specific data passed from Venafi to the

eConnector. In order for all of these components to securely communicate, and to comply with certain

US federal policies, the eConnector makes use of certificates for both authentication and encryption. In

total there are three certificate-based identities that will be required for the eConnector. These three

identities include a Registration Authority (RA) identity, a Web Server identity and a Client identity. The

creation and usage notes for these three identities are described in the following table and in more detail

later in this document.

Page 7: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

5

Table 1 – eConnector Process Flow Identities Certificate Use

Registration Authority Used by TPP to instruct the CA to perform certificate lifecycle actions

(issue, revoke, etc.)

May leverage EPF file, cryptographic token, or HSM to comply with

policy

Web Service Server Identity Used to provide web service server authentication and to establish

SSL/TLS tunnel between PowerShell Script and the Web Service

PowerShell Script Client

Identity

Used to provide PowerShell script client authentication and to establish

SSL/TLS tunnel between PowerShell Script and the Web Service

Page 8: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

6

2 PREREQUISITES AND REQUIREMENTS

Requirements of using Venafi with the Entrust Security Manager is an implementation of the Venafi

Adaptable CA API. Prior to running the eConnector installation script, there are a few prerequisites that

need to be completed. The following section describes these prerequisites and requirements and provides

configuration details.

Before installing the eConnector, make sure that the Java Runtime Environment (JRE), Java

Cryptographic Extensions (JCE), Apache Tomcat Connector, and Apache Tomcat are installed on the

system that will be hosting the eConnector, see Section 3 for installation and configuration guidelines.

While a non-service Apache Tomcat installation can be used, it is recommended to use the Apache

Tomcat service installer in order for Tomcat to run automatically.

2.1 ECONNECTOR PREREQUISITES

IMPORTANT CONSIDERATIONS

1. You can choose to create the eConnector RA credential using Entrust Entelligence Security

Provider (ESP), however it isn’t necessary as the installer will create the credential for you during

the install (Section 4.2). Never create the RA identity using Security Manager

Administration. Security Manager Administration generates v1 profiles which cannot be used

for server login (a requirement for eConnector). The preferred approach is to create the RA

identity account within Security Manager which will generate the activation codes, create the

identity using the eConnector installation tool, and provide the activation codes for the RA

identity.

a. Make sure the certificate type of the RA identity contains the policy object identifier

(OID) 2.16.840.1.114027.10.4. This policy OID is required to be in the certificates of the

RA identity that an eConnector instance will use. Alternatively, you can manually copy

the default Admin Services User Registration certificate type that already contains the

required OID.

b. If you created the RA identity credential as an EPF file, you will need to copy the file to

the eConnector server.

2. Copy the entrust.ini to the eConnector server.

3. You will configure the eConnector instance to either force CRL issue after each revocation or not

during the installation. If you do not require or need that CRL to be issued after each revocation,

you do not need to enable "Force CRLs" in the Security Policy section of the Entrust role for the

RA identity.

The following items need to be completed prior to installing the eConnector:

2.1.1 Create Entrust Security Manager Role

The eConnector implementation uses an Entrust Administrator credential as the RA identity. Within

Security Manager, this identity role must be configured properly in order for the eConnector to be able to

instruct the Security Manager perform the certificate lifecycle operations.

Note: The individual executing the below steps must have the rights necessary within Entrust Security

Manager to create roles and change permissions. Please refer to the Entrust Security Manager Installation

and Configuration and Administration guides for further information.

Page 9: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

7

1. Create a new Entrust role by copying the "User Reg Service (Admin Services)" role and changing

the unique name to be meaningful such as "Venafi Connector Registration Authority". The role

should be for administrator users and not end users.

2. Edit the permissions of the role. At a minimum, the role needs the following permissions:

Certificates

o The role should administer the categories and types of the Entrust users that Venafi

will administer. Currently, only the Enterprise category of certificates is supported.

Directory

o Bind to Directory

Page 10: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

8

Security Policy

o View Security Policy

o Force CRLs

User Templates

o Make sure the role can administer the user templates of all Entrust users Venafi will

issue and administer (i.e. Person and Web Server templates).

Page 11: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

9

Groups

o Must have appropriate groups identified (must be allowed to add and remove users

from the assigned group(s))

Users

o User - General

View

Add

Modify Properties

Revoke Certificates

Set for key recovery

Page 12: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

10

Cancel key recovery

View Activation Codes

Reissue Activation Codes

o User - Advanced

Perform PKIX requests

Create user profile Recover user profile

2.1.2 Create Entrust Security Manager Server Logon Policy

The Role within Security Manager assigned to the RA identity requires a policy that enables Server

logon. Create a new policy or use an existing policy that allows server logon.

Page 13: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

11

2.1.3 Create or Identify a Windows Account for the PowerShell Client

The PowerShell script component of the eConnector requires a user account in order to authenticate to the

eConnector Web Service. This account will be mapped to an SSL/TLS client authentication certificate

during the configuration of the eConnector. This account does not need, and should not have, any

elevated privileges. It is only used for authenticating the PowerShell script as a client. This configuration

process is described in more detail in Section 4.2.24 below.

2.2 SYSTEM PREREQUISITES

1. Windows Server 2012r2 or newer;

2. IIS 7.5 or newer base feature installation (IIS features required by the eConnector will be installed

as part of the eConnector installation PowerShell script);

3. 64-bit Apache Tomcat 8.5 or newer;

4. 64-bit Java JRE 1.8 or newer;

5. Java JCE zip file for the installed Java JRE;

6. 64-bit binary Apache Tomcat Connector zip file (must contain an already built isapi_redirect.dll

file); and

7. The entrust.ini of the Entrust Security Manager CA.

Page 14: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

12

3 INSTALLATION – JAVA, APACHE TOMCAT, IIS WEBSERVER

For co-hosted implementations, Java JRE, Java JCE, Apache Tomcat, IIS webserver, eConnector

Powershell Script, eConnector Java application, and HSM client components (only if using an HSM)

must be installed on all Venafi TPP servers that will be configured within Venafi to communicate with

the Entrust Security Manager CA. For eConnector gateway installations, these modules only need to be

installed on the eConnector gateway server.

3.1 DOWNLOAD JAVA JRE

The Java JRE Installer is located on the Java SE Runtime Environment downloads page and will be

installed on the server hosting Apache Tomcat.

You will need the following Java JRE Installer:

1. jre1.8.0_144 64-bit SE (Server) or later

The eConnector install_configure.ps1 will install Java JRE during the eConnector installation as noted in

Section 4.2.3.

3.1.1 Setting the PATH Environment Variable

The path environment variable will be set during the install_configure.ps1 in Section 4.2.1.

It is also recommended that you ensure the following is set in the system path variable:

C:\ProgramData\Oracle\Java\javapath

Page 15: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

13

3.2 JAVA JCE FOR JAVA JRE

Entrust uses encryption key sizes that are larger than what a default Java JRE allows. In order to enable

larger key sizes, Java JCE can be downloaded and installed to overcome the cryptographic limitations.

The JCE files can either be manually installed or you can choose to allow the install_configure.ps1 script

to install the downloaded files for you in Section 4.2.3.

Take note that the Java JCE Unlimited Strength Jurisdiction Policy Files must be applied each time you

upgrade your Java JRE.

3.2.1 Apply Java JCE Files Manually

Note, if you choose to allow the installer to automatically install the JCE files, skip to Section 3.3.

1. Download the Java JCE Unlimited Strength Jurisdiction Policy Files from Oracle or IBM. Be

sure to download the correct policy file updates for your version of Java:

Java 7 or 8: http://www.oracle.com/technetwork/java/javase/downloads/index.html

IBM: https://www14.software.ibm.com/webapp/iwm/web/preLogin.do?source=jcesdk

2. Extract the downloaded file. The download includes a Readme.txt and two .jar files with the same

names as the existing policy files.

3. Locate the two existing policy files:

local_policy.jar

US_export_policy.jar

On UNIX, look in <java-home>/lib/security/

On Windows, look in C:/Program Files/Java/jre<version>/lib/security/

4. Replace the existing policy files with the unlimited strength policy files you extracted.

5. Restart Apache Tomcat in order for the new Java JCE security policies to be loaded.

3.3 INSTALL 64-BIT APACHE TOMCAT AS A WINDOWS SERVICE

3.3.1 Setting Environment Variables

Apache Tomcat is a Java application and does not use environment variables directly. Environment

variables are used by the Apache Tomcat startup scripts. The scripts use the environment variables to

prepare the command that starts Apache Tomcat. The JRE_Home variable was performed when you

installed the Java JRE and is located in the path variable.

Page 16: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

14

3.3.2 Install Apache Tomcat as a Windows Service

1. Open command line and navigate to %Apache-tomcat%/bin

2. Execute service.bat install

3. Go to Windows Services and start Apache Tomcat

4. Verify successful start-up in the Catalina log file located in <apache-tomcat-

homedirectory>\logs\catalina.todaysdate.log

5. Verify you can browse http://localhost:8080/

6. Click on server status, verify successful logon.

Page 17: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

15

3.4 DOWNLOAD APACHE TOMCAT CONNECTOR

1. Download tomcat-connectors-1.2.42-src.zip from http://apache.mesi.com.ar/tomcat/tomcat-

connectors/jk/. Copy the unzipped file to your Apache Tomcat server, this can be any location

you choose, preferably within your Apache Tomcat installation folder.

Note the location. During the eConnector installation, you will point to the zip (unpackaged) file as it

will get unpackaged and loaded when you click the install button.

3.5 ADD IIS WEBSERVER ROLE AND FEATURES

For co-hosted installations, the IIS webserver role and features must be installed on all Venafi TPP

servers that will be configured within Venafi to communicate with the Entrust Security Manager CA. For

eConnector gateway installations, this only needs to run on the eConnector gateway server.

3.5.1 Install the Web Server (IIS) Role

1. Open the Server Manager and click Add Roles and Features:

Page 18: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

16

Page 20: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

18

4. Click Add Features:

5. Ignore the Features tab and go on:

Page 21: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

19

6. Click Next:

7. The default configuration will be fine. Click Next:

Page 22: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

20

8. Click Install:

9. Click close to complete the IIS Webserver role and feature installation.

Note: The eConnector install_configure.ps1 script will configure IIS and detect and install any missing

roles in Section 4.2.6.

It is recommended that you delete the default site after installing IIS Webserver, see Section 3.5.2 below.

Page 23: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

21

3.5.2 Delete Default Web Site

1. Go back to the Server Manager. Select Internet Information Services (IIS) Manager from the

Manage menu:

2. Expand sites:

3. Right click Default Web Site and delete.

4. Open a command prompt as an administrator and restart IIS <iisreset>.

Page 24: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

22

4 INSTALLATION – ECONNECTOR

The below steps will be performed to install the eConnector on the same server you installed Apache

Tomcat. For co-hosted installations, eConnector must be installed on all Venafi TPP servers that will be

configured within Venafi to communicate with the Entrust Security Manager CA. For eConnector

gateway installations, these modules only need to be installed on the eConnector gateway server. When

preparing the installation package, it’s important to make certain the eConnector folder maintains its

naming integrity, don’t add version numbers, etc. when installing or performing upgrades.

4.1 OPENING AND PREPARING THE INSTALLATION PACKAGE

The zip installation package file contains the following folder structure:

entrustconnector

config

A folder or folders holding the installation and configuration libraries and their associated files. Several

entrust ini files may need to be placed there depending on how many CAs/connector instances will be

used.

entrust

This is an empty folder and is intended to hold Entrust related information such as entrust.ini files and

EPF credentials. Place your entrust.ini file here.

instances

An initially empty folder that will be used to store all eConnector instances. This is useful if you have

more than one instance of the eConnector installed (i.e. in order to permit Venafi TPP to communicate

with more than one Entrust Security Manager CA).

logs

Page 25: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

23

All eConnector logging will be stored here.

install_configure.ps1

The eConnector installation script. Run this file from PowerShell to start the installer.

license.txt

The eConnector product license. This is a license file and for information purposes only.

Unzip the installation package into its final location. The installer will not generate a new installation

location.

4.2 RUNNING THE INSTALLER

Note: The script requires administrator privileges to run and you will be prompted to grant

administrator privileges if you run it from a regular windows account.

4.2.1 Run the script

Open a 64-bit Windows PowerShell and navigate to the eConnector installation folder. The folder will have the

install_configure.ps1 script inside it. There is an optional command line argument to the script called -

java_home where the JAVA_HOME variable can be supplied. This can help if java could not be found or there

are multiple java locations.

Example usage: .\install_configure.ps1 -java_home "C:\Program Files\Java\jre1.8.0_144"

Page 26: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

24

4.2.2 License Agreement

Once the installer loads, the first screen is a review of the license. The license is also contained in a text

file in the root folder of the installer. Click “Accept License Agreement” the green right arrow to proceed

to the next window.

Page 27: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

25

You will see the support agreement screen. This allows you to enter the support agreement information

for the product. The support license code can be obtained through Venafi or Cygnacom Solutions direct.

Click the green right arrow to complete the support license section.

Page 28: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

26

4.2.3 Java JCE

1. The installer will ask for the Java JCE path downloaded in Section 3.2. The installer

automatically detects if the Java JCE is installed. If it is not installed, the installer will attempt to

install it for you and you will see the Install JCE screen. If the Java JCE is already installed, the

installer will simply go to the next installation step.

Page 29: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

27

2. Click the Install Java JCE, then the right arrow button will be enabled allowing you to move to

the next screen. The next screen is a message that you need to restart the installer in order for the

installer to use the new Java JCE security policies.

4.2.4 eConnector Native Library

Entrust requires a native library be installed on the Java library path. This library allows for the use of

Unattended Logon (UAL) files. The installer will automatically detect if the native library is on the java

library path. If it is not, it will show the following screen to help you install it.

The drop down box will contain available locations you can choose from to install the native library. Any

of the choices will work fine.

Page 30: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

28

1. Click Install Library.

2. Click the green right arrow to continue to complete the native library installation.

4.2.5 Apache Tomcat Connector

The Apache Tomcat Connector is used to connect Microsoft IIS with Apache Tomcat. The Apache

Tomcat Connector passes requests for certain relative URLs to Apache Tomcat. The eConnector installer

tries to locate Apache Tomcat. If it finds one or more installed versions, it will display a drop down box

and allow you to choose the version of Apache Tomcat you are currently using. If none are found, you

will be shown a field where you can browse to the installation folder of Apache Tomcat. This folder is the

same as the CATALINA_HOME folder and would contain the bin, conf, and lib folders among others.

Page 31: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

29

1. The next field is where you browse and select the Apache Tomcat Connector zip file. This is the

file you installed in Section 3.4 and must contain a built version of the connector which is usually

called isapi_redirect.dll.

Page 32: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

30

2. Click Install to install the library.

3. Click the green right arrow to continue to complete the Apache Tomcat Connector installation.

4.2.6 Windows IIS Features

IIS was previously installed in Section 3.5.1, this step installs features required by eConnector, and

includes:

Web Server (IIS) (Web-Server)

IIS Client Certificate Mapping Authentication (Web-Cert-Auth)

CGI (Web-CGI)

ISAPI Extensions (Web-ISAPI-Ext)

ISAPI Filters (Web-ISAPI-Filter)

IIS Management Console (Web-Mgmt-Console)

IIS Management Scripts and Tools (Web-Scripting-Tools)

1. Click the Install Features button to automatically install any missing, required features.

Page 33: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

31

2. Click the green right arrow to continue to complete the IIS Windows Feature installation.

4.2.7 Create an eConnector Instance

The next step is to begin the process of creating an eConnector instance. An eConnector instance is a web

service that Venafi will connect to via the Adaptable CA PowerShell script.

The eConnector installation folder contains a subfolder called "entrust". This folder is intended to hold the

entrust.ini files and the RA identity credentials (if stored as a software-based EPF file) for each

eConnector instance.

1. Place a copy of the entrust.ini file for the CA you wish to configure the eConnector instance for in

the entrust subfolder.

Page 34: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

32

4.2.8 Configure Instance URL

1. Create an eConnector instance by setting the URL.

The context path is the URL prefix path for the web application. For simplicity, we recommend setting

the Context Path=EntrustConnector. The service name is the name of the actual web service that the

Adaptable CA PowerShell script will connect to. In this case Service Name=AdaptableCA

The overall form of the URL will be:

https://<hostname>:<port>/<context_path>/<service_name> or

https://<hostname>:443/ EntrustConnector/ AdaptableCA

Page 35: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

33

2. Click Create Entrust Connector.

3. Click the green right arrow to continue to complete the URL instance configuration.

4.2.9 Configure Instance Logging

1. Set the log level to determine the level of logging detail to be included in the logs.

Page 36: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

34

2. Set the number of log files store online before they rotate. Log files are rotated once they reach

the maximum log file size.

3. Set the maximum log size which is the maximum size a log should grow to before being rotated.

This setting must be in kilobytes.

4. Set the log file is the name and location of the log file.

5. Click the green right arrow to complete the logging configuration.

4.2.10 Configure Entrust Administrator RA Identity Credential

As previously noted, the eConnector relies on an RA identity credential in order to instruct the Entrust

Security Manager CA to perform any certificate operations. This RA identity credential can be an

existing credential, as long as it meets the requirements noted above. Or, the eConnector installation and

configuration PowerShell script can create the RA identity credential during the configuration process. If

the RA identity credential is to be created during the configuration, it is necessary to have the Reference

Number and Authorization Code from the CA in order to complete the creation process. In addition to

the RA identity credential, the eConnector installation and configuration PowerShell script will create an

Unattended Logon file in order to permit the eConnector to logon to the Entrust Security Manager CA

using the RA identity credential.

There are three possible operations to perform depending on the situation; Verify, Create UAL, or

Generate User (shown below). It is recommended that you allow the installer to generate the credential

for you during the eConnector install. Before configuring the RA identity credential, it’s important to

determine whether you will create the identity locally as an EPF (noted in Section 4.2.11), or on an HSM

(noted in Section 4.2.12).

Page 37: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

35

1. Generate User. Choose this setting to use a new Entrust user created in Entrust Security

Manager. When the operation is set to Generate User, a new identity credential and UAL will be

generated. A reference number and authorization code are required to complete the identity

credential creation. In addition, a UAL file is generated and then both the identity credential and

UAL file are verified by logging in to the Entrust Security Manager CA using the identity

credential and UAL file.

2. Create UAL. Choose this setting if there is already an existing RA identity credential. A UAL

file will be generated for the identity credential. The identity credential and UAL file are verified

by logging in to the Entrust Security Manager CA using the identity credential and UAL file.

3. Verify. Choose this setting to verify an existing RA identity credential and a corresponding UAL

file. When the operation is Verify, the RA identity credential and UAL files are verified by

logging in to the Entrust Security Manager CA using the identity credential and UAL file.

4.2.11 Generate User – Create EPF Locally

If you’re creating an RA credential on an HSM, skip to Section 4.2.12.

1. Select “Entrust EPF File”

Page 38: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

36

2. Select GENERATE USER from the drop down menu.

Page 39: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

37

3. Browse to location of entrust.ini file and where the user wants the Entrust RA EPF to be created.

Enter EPF password, and supply the Entrust Reference Number and Authorization Code.

4. Select Generate EPF.

5. After generating the EPF, you will see the profiles being configured.

6. Click the green right arrow to continue to complete the RA credential EPF creation.

Page 40: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

38

4.2.12 Generate User – On HSM

If you’re creating an RA credential locally using an EPF, skip to previous Section 4.2.11.

1. Select Hardware Security Module radio button and browse to the cryptographic PKCS11 library.

The PKCS11 library will be provided by your HSM vendor.

Page 41: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

39

2. Select GENERATE USER from the drop down menu.

3. Select the appropriate Slot number based on the HSM.

4. Browse to, and select the location for the entrust.ini file

5. Browse to, and select the location for the Entrust RA UAL to be created.

6. Enter EPF password, and supply the Entrust Reference Number and Authorization Code.

Page 42: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

40

7. Select Generate Credential.

4.2.13 Create UAL for RA Identity

The following instructions apply if the RA identity credential is an EPF or located on an HSM.

1. Select CREATE UAL from the drop down menu.

Note: If you are creating a UAL using an HSM, you will select Create UAL for HSM Operations.

Page 43: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

41

2. Browse to location of entrust.ini file and Entrust RA EPF, and enter the EPF Password.

Note: If you are creating a UAL on an HSM, you will include the slot number.

Page 44: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

42

3. Click Create UAL.

Note: If you are creating a UAL on an HSM, you will also see the slot number.

Page 45: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

43

4. After user Creates UAL, it goes into configuring the profiles.

5. Click the green right arrow to continue to complete the UAL creation.

4.2.14 Verify the RA Identity with UAL

The following instructions apply if the RA identity credential is an EPF or located on an HSM.

1. Select VERIFY in the drop down menu.

Note: If you are verifying an RA identity credential using an HSM, you will select Verify for HSM

Operations.

Page 46: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

44

2. Browse to entrust.ini and Entrust RA EPF location then click Verify.

Note: If you are verifying an RA identity credential on an HSM, you will also see the slot number.

3. Click the green right arrow to continue to complete the credential verification process.

Page 47: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

45

4.2.15 Configure eConnector Instance Profiles

An eConnector Instance Profile is a mapping between the user type template, the certificate type, and the

friendly name. The user type template and certificate type come directly from your Entrust Security

Manager CA instance. These profiles need to be configured in the eConnector.

4.2.16 Add a Profile

If you’re editing a profile, skip to Section 4.2.17.

1. To add a profile, click the plus button.

Page 48: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

46

2. In the next screen, enter a unique profile name (a friendly name – i.e. “Web Server”, “Web Server

with Dual Usage”, etc.), then select the user type and certificate type. Click the Add button to add

the new profile. The certificate types must be a single key pair definition within the Entrust

Security Manager CA. The Venafi TPP does not currently support multi-key pair certificate

definitions via the Adaptable CA driver.

3. Click add to save your changes or cancel to return to the previous screen without saving.

OTHER PROFILE OPTIONS

If you’re creating a new profile, skip to previous Section 4.2.16.

Page 49: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

47

4.2.17 Edit a Profile

1. To edit a profile, select the profile to edit and then click the wrench button.

2. In the next screen, edit the profile name, user, and certificate types.

3. Click save to save your changes or cancel to return to the previous screen without saving.

Page 50: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

48

4.2.18 Remove a Profile

If you’re creating a new profile, skip to previous Section 4.2.16.

1. To remove a profile, select the profile to remove and then click the minus button.

Page 51: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

49

2. In the next screen, confirm the removal by clicking on the delete button.

3. Profile is deleted. Click the right arrow to proceed to save the eConnector settings.

Page 52: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

50

4.2.19 Save the eConnector Instance Settings

The final step in creating a new eConnector Instance is reviewing and then saving the settings.

1. Click Save Settings.

2. Click the green right arrow to continue to complete the IIS configuration.

4.2.20 Complete IIS Configuration

Once an eConnector Instance has been created, the next step is to configure IIS to provide service for it.

Before configuring IIS, the installer must read the current IIS settings.

Page 53: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

51

1. Click the right arrow to continue.

Page 54: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

52

2. Once the IIS settings have been read, you can either create a new website to host the eConnector

or enter the name of an existing website. It is recommended that you create a new website for

eConnector.

3. Select the checkbox to create a new website and enter a unique name that defines the eConnector

such as “Venafi eConnector.”

4. Click the green forward arrow to proceed to setting the Website SSL Certificate.

4.2.21 Setting the Website SSL/TLS Certificate

As previously noted, a web server certificate is required for the web server of the eConnector gateway. If

the certificate does not exist, the installer will walk you through the certificate creation process using the

RA identity credential created in Section 4.2.10 above.

The installer will allow you to select an existing web server certificate from within the server's

LocalMachine personal certificate store, browse to a PFX file, or create a new PFX file issued from the

configured Entrust Security Manager CA.

Option 1: Selecting an Existing Web Server Certificate

1. Select existing certificate

2. Selecting the certificate option allows for selecting an existing certificate in the server's

LocalMachine personal certificate store. Highlight the certificate from within the table and click

the button to verify the certificate.

Page 55: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

53

3. The verification process will confirm that the certificate is valid and that the revocation

information for the certificate can be retrieved. Once the certificate has been successfully

verified, click the green right arrow to proceed.

Page 56: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

54

Option 2: Browse to SSL Certificate Pfx File

1. The browsing option allows for selecting an existing PFX file and then it installs it into the

LocalMachine personal certificate store. Browse to the web server certificate and enter the

password required to access the associated private key.

2. Click the Install button to install the certificate and corresponding private key.

3. Once the certificate and private key have been successfully installed, click the green right arrow

to proceed.

Option 3: Creating a new SSL Certificate

Creating a new web server certificate will instruct the Entrust Security Manager CA to generate a new

key pair and issue the corresponding web server certificate. The new web server certificate and

associated private key will be written to a PFX file, which will then be imported into the web site

configuration.

Page 57: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

55

1. Select Create a new SSL certificate.

2. Click OK

Page 58: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

56

3. Enter the value for the common name. This value should match the hostname of the eConnector

server (or be sure to enter the correct hostname as a DNS value in the SubjectAltName field of

the certificate to avoid a name mismatch error when browsing to the website).

4. Select the Search Base dropdown and the Entrust User Distinguished Name (DN) will pre-

populate. Then enter the name and location for the PFX file and password in the correct fields.

5. Click the verify DN button to confirm that the DN is valid and that the parent DN is accessible.

Note: If the web server identity does not exist in the Entrust Security Manager CA, the Connector

Profile selection box will be shown. This is where you will tell the installer what certificate

profile (i.e. Web Server) to use when creating this new web server identity.

6. Click the green right arrow to continue to proceed to setting the SAN values (if applicable) within

the certificate. If the web server identity already exists within the Entrust Security Manager CA,

any configured Subject Alternative Name (SAN) entries will be shown in the table. SANs can be

added, edited or removed.

Page 59: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

57

7. Click the Plus button to add SAN values, if desired. Or, if desired, you can select a SAN value

listed in the table and click the wrench button to edit the SAN type of value, or click the minus

button to delete the SAN value from the certificate.

8. Finally, click the Generate PFX button to create the certificate and write the PFX file.

9. Click the green right arrow to proceed to installation of the new PFX file.

Page 60: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

58

10. Browse to the newly created PFX file and enter the corresponding password.

11. Click the Install button to install the certificate and private key from the PFX file.

12. Click the green right arrow to proceed with creating the HTTPS binding.

4.2.22 Create an HTTPS Binding

The following screen appears in the installer when creating a new website or updating an existing website

that does not have an https binding.

The IP address can either be an asterisk or an IP address. Both the port number and hostname must also

be specified.

Page 61: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

59

1. Enter the IP Address of the eConnector web site. Or, use the “*” to represent all IP address

available on the web server.

2. Enter the TCP port number that the eConnector web site will listen on for HTTPS connections

(typically 443).

3. Enter the hostname for the eConnector web server.

4. Click the Verify button to confirm the information entered. Once the verify process has

completed, click the green right arrow to proceed.

4.2.23 Complete Website Configuration

When creating a new website, the following screen will appear to show the details of the changes to be

made to IIS. Clicking on the create website button will create and configure the website.

Page 62: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

60

1. Click on the Create Website button to create the website and configure the HTTPS binding.

2. Once the website has been created and configured, click the green right arrow to proceed.

If the web site being configured already exists on the web server, the configuration information will be

used to update the existing website. When updating an existing website, the following screen will appear

to show the details of the changes to be made to IIS.

Page 63: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

61

3. Click the Update Website button to apply the configuration updates to the web site, including

updating the HTTPS binding.

4. Once the update process has completed, click the green right arrow to proceed with verifying

connectivity to the eConnector website.

Note: Make sure that Apache Tomcat is running before clicking the link displayed in the dialog box.

5. Click on the link to check the website configuration which will open a web browser and verify

the eConnector is active and accessible.

Page 64: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

62

If the eConnector website is functioning correctly, your web browser will display a message indicating

that the Entrust Connector service is Active.

4.2.24 Manage Client Authentication (CAuth) Mappings

ABOUT CLIENT AUTHENTICATION MAPPING

eConnector requires client authenticated SSL to secure the web service. This means that the client must

authenticate with a trusted certificate in order to access the eConnector web service. In this case, the client

is the Entrust Adaptable CA PowerShell script.

Note: As noted in Appendix A, the client certificate must be installed in the LocalMachine certificate

store of the Venafi TPP server in order for the Entrust Adaptable CA PowerShell script to access it.

The Entrust Adaptable CA PowerShell script accesses the web service using the information in the Venafi

Username Credential that will be created in Section 5.1.2. The username value of the Venafi Username

Page 65: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

63

Credential is the URL of the eConnector instance web service. The password value of the Venafi

Username Credential is the thumbprint of the client certificate to present to the web service.

The previously configured IIS website requires client authentication for the SSL session. The client

authentication used by the Adaptable CA PowerShell script requires a valid Windows account and

certificate asserting client authentication that will created in Step 4.2.25 below.

The eConnector installation and configuration PowerShell script provides three options for working with

the Client Authentication (CAuth) mapping:

1. Add (Refer to Section 4.2.25) – used to create a new client authentication mapping (between the

Windows account and the client authentication certificate). If more than one Venafi TPP server

will be connecting to an eConnector instance, a new CAuth mapping can be made for each Venafi

TPP server.;

2. Edit – used to edit an existing CAuth mapping, including changing the Windows account

password or updating the client certificate; and

3. Remove – used to delete an existing CAuth mapping.

4.2.25 Create Certificate for Mapping

1. Create a new SSL certificate (client authentication certificate).

The first step in creating a new client authentication mapping is to create a client certificate that will be

mapped to a Windows user account. It is also recommended that you add the certificate usage within the

common name, example CN=Venafi ClientAuth_SSL. In this particular scenario, we will create a new

certificate.

Page 66: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

64

Creating a new certificate will generate a new certificate from an Entrust Security Manager CA using a

configured eConnector instance.

2. Choose which connector to use.

Page 67: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

65

3. Enter the common name value for the client authentication identity;

4. Select the Search Base dropdown and the Entrust User Distinguished Name (DN) will

prepopulate;

5. Enter the PFX file and password in the correct fields;

6. Enter the location where you want to store the PFX file;

7. Enter a password used to access the PFX file.

8. Click the verify DN button to confirm that the DN is valid and that the parent DN is accessible.

Note: If the client authentication identity does not exist in the Entrust Security Manager CA, the

Connector Profile selection box will be shown. This is where you will tell the installer what

certificate profile (i.e. Web Client) to use when creating this new client authentication identity.

9. Click the green right arrow to continue to proceed to setting the SAN values (if applicable) within

the certificate. If the client authentication identity already exists within the Entrust Security

Manager CA, any configured Subject Alternative Name (SAN) entries will be shown in the table.

SANs can be added, edited or removed.

Page 68: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

66

10. Click the Plus button to add SAN values, if desired. Or, if desired, you can select a SAN value

listed in the table and click the wrench button to edit the SAN type of value, or click the minus

button to delete the SAN value from the certificate.

11. Finally, click the Generate PFX button to create the certificate and write the PFX file.

12. Click the green right arrow to proceed to installation of the new PFX file.

Page 69: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

67

13. Verify certificate. Part of the verification process is checking if the certificate contains the client

authentication extended key usage.

14. Once the verification process has completed, click the green right arrow to proceed to the

Windows User information.

4.2.26 Additional Options for Choosing the Client Authentication Certificate

In addition to creating a CAuth certificate, you also have the option to select an existing CAuth certificate from the

LocalMachine certificate store, or import an existing certificate and private key from a PFX file.

Selecting an Existing Certificate

Selecting an existing certificate will seek out and display certificates from the LocalMachine personal

store that have the client authentication enhanced key usage setting, also see Appendix A.

Page 70: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

68

1. Select the option to Select an Existing Certificate and click OK.

2. Select the existing CAuth certificate from the table.

Page 71: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

69

3. Click the Verify button. Once the certificate verification process has completed successfully,

click the green right arrow to proceed to the Windows User information.

Browse to SSL Certificate PFX File

This option allows you to import a certificate and its associated private key from an existing PFX file.

1. Select the option to browse to SSL Certificate PFX file.

2. Click OK to proceed.

Page 72: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

70

4. Browse for, and select, an existing PFX file;

5. Enter the password for the PFX file;

6. Click the Read PFX button to read and import the PFX contents.

7. Once the certificate contents have been processed, click the green right arrow to proceed with the

Windows User information.

Page 73: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

71

4.2.27 Enter the Windows User Information

1. Enter the Windows user and password previously created in Section 2.1, Step 3 into the fields.

2. Click on the verify button to authenticate the username and password to ensure they’re valid.

Page 74: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

72

4.2.28 Verify and Add the New Mapping

1. Review the new client authentication mapping details and then click the Add Mapping button to

add the mapping. Or, click the Cancel button to return without adding the mapping.

4.2.29 Editing Mappings

There are two items to edit in a client authentication mapping, the Windows user account information and

the client certificate.

Page 75: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

73

Updating the Windows User Information

1. Click on the Update Windows Account check box to update the Windows account

information.

2. Edit the Windows user and password information as needed. Clicking on the verify button

authenticates the username and password to ensure they’re valid.

Note: The Windows user doesn’t require any privileges and is only used by IIS to authenticate the

username and password. The same Windows user may be used for multiple client authentication

mappings.

Page 76: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

74

Updating the Client Authentication Certificate

1. Click on the Change Certificate check box to update the client certificate. Refer to Section

4.2.26 for instructions on creating a new, or selecting a different CAuth certificate.

4.2.30 Remove Mapping

Review the client authentication mapping details and then either remove the mapping or cancel.

Page 77: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

75

Click the Remove button to delete the CAuth mapping. Or, click the Cancel button to return without

removing the CAuth mapping.

4.2.31 Complete Website Client Authentication Configuration

The next step is to update IIS and add the new Client Authentication mapping.

1. Verify the summary of changes and then click on the update website button.

Page 78: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

76

1. After updating the client authentication settings, verify that the website requires and accepts the

certificate. Click on the link provided to verify the connection to the eConnector instance. You

should be asked to present a client certificate to visit the connector web service.

Page 79: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

77

Note: During verification, you will be prompted to provide the CAuth certificate.

4.3 COMPLETE INSTALLATION

The final screen shows the next steps to perform. As previously noted, a new username credential that

parallels the URL and the password is the certificate thumbprint and will be used to create the credential

in Venafi. Venafi will use this information to connect to the eConnector instance by using the Entrust

Adaptable CA PowerShell script.

The client certificate that was selected must be installed on the Venafi server in the LocalMachine

personal certificate store. The Entrust Adaptable CA PowerShell script will use the certificate to connect

to the eConnector instance.

Page 80: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

78

Copy the User Name value and the Password Value to the clipboard. These values will be required in

order to complete the Username Credential within Venafi. You will also need to copy the Configured

Profiles, as these values will be required when configuring the Custom Field within Venafi Aperture.

Page 81: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

79

5 VENAFI CONFIGURATION

When configuring an Adaptable CA template in Venafi Trust Protection Platform, you must specify two

items; username credential and custom fields. When Venafi requests an administrative action on the

Entrust Security Manager CA, it must include these two items in its request to the Entrust Adaptable CA

PowerShell script. The below section describes how to configure the custom fields and username

credential within Venafi.

In order to complete the Venafi configuration, you must be logging in to Venafi with Administrative

privileges that permit you to create and edit a Username object within WebAdmin as well as create and

edit Custom Fields within Aperture.

5.1.1 Create a Venafi Custom Field

The Entrust Adaptable CA PowerShell script requires a custom field be created in the Venafi Aperture

application and is used for creating new users. The profile selected will be converted into a

corresponding Entrust user type and certificate type by the web service.

The custom field should have a meaningful name. When creating it, it must be defined as a single select

list. The contents of the list will be the eConnector configured profile names.

1. Create a custom field for each eConnector instance.

Note: The field must be a list type and be single select only. The values of the list custom field must

match the profile names that are configured in the eConnector instance.

Page 82: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

80

Note: You can change the display name to any friendly name you want, however the name sent

to the script must match what is configured in the connector. If there is a mismatch in the profile

name, the eConnector will return an error.

5.1.2 Create the Venafi User Name Credential

The Entrust Adaptable CA PowerShell script uses this credential to authenticate with the eConnector web

service and perform administrative operations on the Entrust Security Manager CA.

The user name value of the credential must be the URL of the eConnector instance web service. The

password value of the credential must be the thumbprint of the client authentication certificate. The client

Page 83: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

81

authentication certificate must be installed in the LocalMachine certificate store on the Venafi Trust

Protection Platform server in order that it may be used by the Entrust Adaptable CA PowerShell script.

1. Open Venafi Web Administration.

2. Right click the credential policy container (this is typically located under the Administration

container)

3. Click Add > Credential > Username Credential

4. Add a Description and the User Name and Password you recorded earlier (eConnector URL and

certificate thumbprint).

5. Click save.

Page 84: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

82

5.1.3 Create the Venafi Adaptable CA Template

1. Right click the Certificate Template policy container.

2. Click Add > CA Template > Adaptable

There are three settings which must be set:

a. Copy the Adaptable CA Entrust.ps1 script from the eConnector installation package over to the

Venafi server and place it in Program Files\Venafi\Scripts\AdaptableCA

b. Choose the Entrust Adaptable CA PowerShell script

c. Choose the User name credential (described above) and Validate

d. Add the custom field (described above) and save

Page 85: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

83

6 POST ECONNECTOR CONFIGURATION (OPTIONAL)

Post installation configuration of the eConnector may include any of the following:

Adding another eConnector Instance

Editing an eConnector Instance

Removing an eConnector Instance

Changing an administrator RA password

Updating the Client Authentication Settings

Updating the certificates

Changing the windows user or password

To invoke the post install configuration wizard, you must run the install_configuration.ps1 script from

PowerShell as an administrator.

In performing operations, the script connects to an eConnector instance to create, recover, retrieve, or

revoke certificates. An eConnector instance requires an Entrust administrator user to perform the

certificate management operations.

6.1 POST INSTALLATION CONFIGURATION STEPS

6.1.1 Perform Post Installation Configuration of the eConnector (Optional)

1. Open PowerShell and run the install_configure.ps1 script again to perform post installation

configuration of eConnector.

Page 86: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

84

2. Click on the Accept License Agreement checkbox.

3. Click on the File dropdown menu to select your operation.

Note: The configuration tool looks for configuration issues while loading and it will prompt you to fix

them.

It checks for the following issues:

a. Java Cryptographic Extension not installed. This can occur when Java has been updated.

b. eConnector native library was not found

c. Apache Tomcat folder does not exist. This can occur when Apache Tomcat has been updated.

Page 87: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

85

APPENDIX A – CERTIFICATE STORES

6.2 ECONNECTOR GATEWAY SERVER

6.2.1 IIS Binding

Within IIS, the HTTPS binding reflects the SSL certificate that was created in Section 4.2. This

certificate is located in the Local Computer Personal store.

6.3 LOCAL COMPUTER CERTIFICATE STORE

6.3.1 Personal Store

The Local Computer Personal certificate store must contain the SSL certificate used in the HTTPS

binding. This certificate was created in Section 4.2.

6.3.2 Trusted Root Certificate Authorities Store

The eConnector must be able to properly validate the web server and client certificates. In order for this

validation to succeed, it is necessary to ensure that the Root CA that issued these certificates is contained

within the Trusted Root store of the Local Computer.

Page 88: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

86

6.4 VENAFI TPP SERVER(S)

Each of the Venafi TPP servers that will be configured within Venafi to communicate with the Entrust

Security Manager CA via the eConnector must be configured to perform certificate-based client

authentication. The certificate used for this authentication was created in Section 4.2.

6.4.1 Local computer store

Personal Store

The Local Computer Personal store must contain the client authentication certificate that is used to

establish the SSL/TLS encrypted session between the PowerShell script and the eConnector web server.

Trusted Root Certificate Authorities Store

As with the web server authentication certificate, client authentication certificate must also be verifiable

up to the issuing Root CA. In order for this process to succeed, it is necessary to ensure that the Root CA

certificate is contained in the Local Computer Trusted Root CA certificate store.

Note: If there is an intermediate CA in the certificate validation path, you will need to include these

certificates in the Intermediate Certification Authorities stores to uphold the certificate trust.

Page 89: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

87

APPENDIX B – ADD A NEW ECONNECTOR

Multiple instances of eConnector are supported on the same gateway. This configuration would be

necessary if the eConnector gateway will be communicating with multiple Entrust Security Manager CAs.

1. Select "New Connector" from the File menu. In the first screen enter the new instance context

path and service name. These values form the URL of the new eConnector web service.

2. Follow steps in previous sections for Administrator Credential, Instance Profiles, and certificate

creation.

Page 90: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

88

APPENDIX C – EDIT AN ECONNECTOR

Select "Edit Connector" from the File menu.

When editing an instance of eConnector, you are presented with the options to remove the instance of the

eConnector, perform an EPF operation, or change the entrust.ini file. If there are multiple eConnector

instances configured on the server, you can select the instance to edit using the drop-down selection.

Clicking the remove button provides a prompt to confirm the removal of the selected eConnector

instance.

On the lower half of the edit instance pane, the eConnector instance entrust.ini and RA identity credential

EPF locations are shown. In addition, there is an EPF Operation drop-down selection box with four

possible values.

Page 91: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

89

Verify - Select this option to simply verify the credential and corresponding UAL file.

Change Password - Select this option to change the EPF file password. A new UAL file will be

generated and then verified.

Rebind UAL - Select this option to generate a new UAL file.

Create/Recover - Select this option to generate a new EPF by supplying Entrust activation codes.

Once the EPF has been generated, a new UAL file will be created and then verified.

Changing the EPF password allows you to enter the current password, and then the desired new

password.

Page 92: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

90

Rebinding the UAL file requires the current EPF password. The UAL file is verified after creation.

Page 93: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

91

When creating or recovering the EPF file, make sure to check the new user check box if the Entrust user

is new. If recovering an existing Entrust user, do not check the new user check box.

Enter the desired EPF password and the Entrust User's current activation codes (reference number and

authorization code).

Page 94: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

92

APPENDIX E – UPDATING THE ECONNECTOR INSTANCE PROFILES

Profiles need to be configured in both an eConnector instance and in Venafi. When the Venafi uses the

Adaptable CA PowerShell script to create a new certificate, the profile it uses is mapped to specific

Entrust User and Certificate type.

Only the profile names need to be configured in the Venafi application, but the eConnector instance needs

to map the profile name to specific Entrust User and Certificate types that are configured in the Entrust

Security Manager CA.

Note: You must also make changes to the corresponding Venafi custom field. The profile names must be

the same in both lists.

To add a profile, click the plus button. In the next screen, enter a unique profile name, then select the user

type and certificate type. Click the Add button to add the new profile.

Page 95: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

93

To edit a profile, select the profile to edit and then click the wrench button. In the next screen, edit the

profile name, user, and certificate types. Click the Save button to add the new profile.

Page 96: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

94

To remove a profile, select the profile to remove and then click the minus button. In the next screen,

confirm the removal by clicking on the delete button.

Page 97: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

95

APPENDIX F – UPDATING THE MAPPING

Clicking the Update Mapping button on the Edit Mapping screen updates the IIS client authentication

mapping with the new values.

Page 98: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

96

APPENDIX G – REMOVE THE MAPPING

Review the client authentication mapping details and then either remove the mapping or cancel.

Page 99: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

97

APPENDIX H – UPGRADING AN EXISTING INSTALLATION

To upgrade an existing eConnector installation, run the upgrade.ps1 PowerShell script from a 64-bit

PowerShell window.

Note: Don’t overwrite existing installation with the most recent version.

The first screen displayed by the upgrade tool after loading shows the version of EntrustConnector the

tool will upgrade to.

Clicking the right arrow will display the license agreement which must be accepted in order to continue

the upgrade process.

Page 100: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

98

The next screen performs the eConnector upgrade. The first step is to browse to the eConnector

installation folder. This is the folder where the original eConnector was installed.

Then, click the upgrade button to upgrade the eConnector.

Page 101: Entrust Connector (eConnector)...1 ENTRUST CONNECTOR (ECONNECTOR) OVERVIEW The eConnector is an implementation of the Venafi Adaptable CA API for Entrust Security Manager based Certification

eConnector Installation Guide

99

The final screen shows the version that eConnector was upgraded to and provides an exit button to exit

the upgrade tool.