Entrust Connector (econnector) Venafi Trust Protection Platform

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

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 1

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 2

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 3

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. 4

Identities Registration Authority Web Service Server Identity PowerShell Script Client Identity Table 1 econnector Process Flow Certificate Use 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 Used to provide web service server authentication and to establish SSL/TLS tunnel between PowerShell Script and the Web Service Used to provide PowerShell script client authentication and to establish SSL/TLS tunnel between PowerShell Script and the Web Service 5

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. 6

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 7

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). 8

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 9

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. 10

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. 11

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 12

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. 13

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-tomcathomedirectory>\logs\catalina.todaysdate.log 5. Verify you can browse http://localhost:8080/ 6. Click on server status, verify successful logon. 14

3.4 DOWNLOAD APACHE TOMCAT CONNECTOR 1. Download tomcat-connectors-1.2.42-src.zip from http://apache.mesi.com.ar/tomcat/tomcatconnectors/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: 15

2. Click Next until you reach the Select Server Roles dialog window: 3. Select Web Server (IIS): 17

4. Click Add Features: 5. Ignore the Features tab and go on: 18

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

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. 20

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>. 21

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 22

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" 23

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. 24

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. 25

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. 26

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. 27

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. 28

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. 29

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. 30

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. 31

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 32

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. 33

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). 34

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 35

2. Select GENERATE USER from the drop down menu. 36

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. 37

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. 38

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. 39

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. 40

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. 41

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

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. 43

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. 44

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. 45

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. 46

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. 47

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. 48

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. 49

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. 50

1. Click the right arrow to continue. 51

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. 52

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. 53

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. 54

1. Select Create a new SSL certificate. 2. Click OK 55

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 prepopulate. 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. 56

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. 57

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. 58

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. 59

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. 60

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. 61

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 62

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. 63

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. 64

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. 65

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. 66

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. 67

1. Select the option to Select an Existing Certificate and click OK. 2. Select the existing CAuth certificate from the table. 68

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. 69

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. 70

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. 71

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. 72

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. 73

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. 74

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. 75

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. 76

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. 77

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. 78

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. 79

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 80

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. 81

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 82

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. 83

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. 84

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. 85

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. 86

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. 87

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. 88

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. 89

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

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). 91

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. 92

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. 93

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. 94

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. 95

APPENDIX G REMOVE THE MAPPING Review the client authentication mapping details and then either remove the mapping or cancel. 96

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. 97

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. 98