Installation and Configuration Guide

Transcription

1 Entrust Managed Services PKI Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0 Date of Issue: July 2009

2 Copyright 2009 Entrust. All rights reserved. Entrust is a trademark or a registered trademark of Entrust, Inc. in certain countries. All Entrust product names and logos are trademarks or registered trademarks of Entrust, Inc. in certain countries. All other company and product names and logos are trademarks or registered trademarks of their respective owners in certain countries. This information is subject to change as Entrust reserves the right to, without notice, make changes to its products as progress in engineering or manufacturing methods or circumstances may warrant. Obtaining technical support For support assistance by telephone call one of the numbers below: in North America outside North America You can also Customer Support at: [email protected] Export and/or import of cryptographic products may be restricted by various regulations in various countries. Export and/or import permits may be required. 2 Auto-enrollment Server 7.0 Installation and Configuration Guide

3 TOC About Auto-enrollment Server Overview Auto-enrollment Server system components Tier Tier Tier How the auto-enrollment process works Auto-enrollment request Choice of certificate type and role Auto-enrollment decision procedure Enrollment and recovery queues for administrator approval How the distinguished name (DN) is created How the subjectaltname is created How the subjectaltname is created for domain controller certificates 17 Preparing for installation Planning your installation What you should have from Entrust for the pre-installation Pre-installation tasks Step 1: Installing the Web Server Step 2: Obtaining a Web server certificate Step 3: Assigning the certificate to your Web server Step 4: Enabling SSL on your Web server Step 5: Configuring integrated Windows authentication Step 6: Testing the SSL-enabled Web server Step 7: Obtaining a certificate for Auto-enrollment Server

4 Installing Auto-enrollment Server What you should have from Entrust for the installation of Auto-enrollment Server Installing Auto-enrollment Server Checking the Auto-enrollment Server installation Verify adminservice.log file Verify the Web server is passing requests to Auto-enrollment Server 86 Verify installation log file Verify configuration log file Customizing the Auto-enrollment Server What you should have from Entrust for Auto-enrollment Server customizations Customizing the certificate type and user role Configuring a default certificate type Configuring a default User Role Configuring the client information setting Customizing certificate lifetimes Customizing a user s Distinguished Name (DN) Customizing a search base for enrolling clients Configuring the DNS name Configuring queuing Enabling queuing in Auto-enrollment Server Configuring the ae-defaults.xml file to queue requests Configuring the queuing monitor Approving or rejecting requests in Administration Services Troubleshooting Logging configuration Setting the log level Setting the log file location Setting the maximum log file size Setting the number of backup log files allowed Setting the maximum message length Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

5 Time synchronization Error messages Glossary of terms Writing your own DN Builder implementation code DN Builder examples Customizing the DN builder code DistinguishedNameBuilderDefaultImp Customizing the default DN Builder implementation Constructor Summary Method Summary Constructor Detail Method Detail ActiveDirectoryUserInfo Method Summary Method Detail Index

6 6 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

7 1 About Auto-enrollment Server The Entrust Authority Auto-enrollment Server creates certificates and sends these transparently to an Entrust Entelligence Security Provider for Windows client. The following topics provide an introduction to Auto-enrollment Server: Overview on page 8 Auto-enrollment Server system components on page 9 How the auto-enrollment process works on page 13 7

8 Overview The Auto-enrollment Server simplifies certificate deployment by providing automatic enrollment of keys and certificates to users and computers. Enrollment is also transparent to the administrator (the level of transparency to the end-user depends on the user key store selected for key protection). The Auto-enrollment Server communicates with the Security Provider for Windows client to automatically deliver a certificate to Windows-based users or computers. Auto-enrollment Server can provide a certificate to the following Windows-based machines: Laptops and desktops Microsoft Windows IIS Web browsers and servers Domain Controllers Authentication clients and servers (RRAS, IAS, VPN, Radius Servers) Note: The Security Provider for Windows client must be online at the time of the initial auto-enrollment request, in order for the request to be processed by Auto-enrollment Server. When the enrollment request is sent from the Security Provider for Windows client to Auto-enrollment Server, the enrollment may be processed automatically or the enrollment may be queued. Queuing is an optional feature, which takes an enrollment request and leaves it at the Auto-enrollment Server for approval by an administrator. In the case of an automatically processed request, Auto-enrollment Server contacts the Certification Authority (CA) for approval. Once the auto-enrollment request has been automatically approved or approved by the administrator in the case of queuing, the authorization code and reference number are passed to the Security Provider for Windows client. The Security Provider for Windows client uses the authorization code and reference number to complete the enrollment process. 8 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

9 Auto-enrollment Server system components The following figure provides an illustration of the Auto-enrollment Server system components in a Three-Tier client/server environment: Figure 1: Auto-enrollment Server system components About Auto-enrollment Server 9

10 Tier 1 Entrust Entelligence Security Provider for Windows (Security Provider) is known as the tier 1 client component in this three-tier client/server environment. Note: You host the Security Provider client. Entrust Entelligence Security Provider for Windows Entrust Entelligence Security Provider for Windows (Security Provider) is the client that transparently communicates with Auto-enrollment Server to enroll certificates. Auto-enrollment Server transparently issues certificates to a user or computer through Security Provider. Auto-enrollment is enabled per-ca by configuring the following registry values: AutoEnrollUserURL AutoEnrollMachineURL You can configure the registry values in the Windows registry of the machine in which Security Provider is installed or through Security Provider s Custom Installation wizard (Specify Entrust PKI Information page). For more information on adding these values, see the Entrust Entelligence Security Provider for Windows Administration Guide. A CA can have user auto-enrollment and machine auto-enrollment enabled for it. If the AutoEnrollUserURL value is present, user auto-enrollment is enabled for that CA. If the AutoEnrollMachineURL value is present, machine auto-enrollment is enabled for that CA. Both values support a list of Auto-enrollment Server URLs in case connections to multiple Auto-enrollment Servers should be attempted. If a connection to the first Auto-enrollment Server does not work, the second server URL is tried, and so on. Once a connection is established with one Auto-enrollment Server, connections to other servers are not attempted. Tier 2 The Microsoft Internet Information Services (IIS) Web Server and Tomcat Application Server are known as tier 2 in the three-tier client/server environment. The Web Server and Application Server provide the middle-tier processing between Security Provider and the CA. Note: You host the IIS Web Server and the Tomcat Application Server. 10 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

11 Microsoft Internet Information Services (IIS) Web Server Security Provider for Windows communicates with the Microsoft IIS Web Server through a firewall. SSL encryption must be used on the Web Server to secure the connection between Security Provider and Auto-enrollment Server. Security Provider communicates directly with an SSL-enabled Microsoft IIS Web Server over HTTPS. The Microsoft IIS Web Server is configured to authenticate Security Provider through Windows Integrated Authentication using the NTLM or Kerberos authentication methods. Tomcat Application Server The Tomcat Application Server is connected directly to the Microsoft IIS Web Server. The Microsoft IIS Web Server communicates through a Tomcat isapi filter to a JK2 Connector in the Tomcat Application Server. The JK2 Connector passes information to the Auto-enrollment Server located in the Tomcat Application Server. Tier 3 Entrust Managed Services PKI certification authority (CA) is known as the tier 3 server component in a three-tier client/server environment. Note: Entrust Managed Services PKI hosts the CA. Entrust Managed Services PKI certificate authority Entrust Managed Services PKI runs the certification authority (CA) for the Auto-enrollment Server system. The main functions the CA is to: create certificates for all public keys create encryption key pairs provide a managed, secure database of information that allows the recovery of encryption key pairs enforce the security policies defined by your organization publish Certificate Revocation Lists (CRLs) publish Policy Certificates Auto-enrollment Server must be able to communicate with the XML Administration Protocol (XAP) Server running as part of the CA. Communication between these components is XAP over HTTPS. About Auto-enrollment Server 11

12 Directory The majority of information requests involve retrieving certificates. To make this information publicly available, the CA uses a public repository known as a directory. The directory is an LDAP (Lightweight Directory Access Protocol) compliant directory service. Information that is made public through the directory includes: user certificates lists of revoked certificates client policy information Public encryption certificates for each user, certificate revocation lists (CRLs), and other information are written from the CA to the directory. Auto-enrollment Server Servlets need access to the directory in order to log in to their profiles. Database The database is under the control of Entrust Managed Services PKI and acts as a secure storage area for all information related to the CA. The database stores: the CA signing key pair (this key pair may be created and stored on a separate hardware device rather than the database) user or computer status information the encryption key pair history (including all decryption private keys and encryption public key certificates) for each user and computer the verification public key history (including all verification public key certificates) for each user and computer the validity periods for signing key pairs, encryption key pairs, and system cross-certificates Security Officer and administrator information CA policy information revocation information Note: All information stored in the database is secured to protect against tampering. 12 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

13 How the auto-enrollment process works The following sections provide a high-level view of the auto-enrollment process: Auto-enrollment request on page 13 Choice of certificate type and role on page 13 Auto-enrollment decision procedure on page 14 Enrollment and recovery queues for administrator approval on page 14 Auto-enrollment request Security Provider sends an auto-enrollment request over SSL to the Microsoft IIS Web Server. Windows Authentication is performed, using the NTLM or Kerberos authentication protocol, and this determines the Windows domain and name of the remote client that sent the request. The Auto-enrollment Server builds a distinguished name (DN) from the Windows domain and user name found in the auto-enrollment request. There may be messages sent from the Auto-enrollment Server to the directory to determine the first and last names. An authentication servlet in the Tomcat Application Server receives the request through an ISAPI connector. The client is authenticated primarily through membership in a Windows domain name. The user s Windows domain and account name must be mapped by the server to an X.500 distinguished name (DN). The default mapping creates a common name from the user s Windows domain login name. This is received by the authentication component. The administrator can choose to customize the distinguished name (DN) builder implementation, instead of using the default. The DistinguishedNameBuilder interface can be used to define your own mapping procedure. Refer to the section Customizing a user s Distinguished Name (DN) on page 97. Choice of certificate type and role The choice of certificate type and user role is made by Auto-enrollment Server and is configurable in the ae-defaults.xml file. Refer to the section Customizing the certificate type and user role on page 91 for further information. When Auto-enrollment Server decides the Certificate Type and Role that will be used for the enrollment, it communicates this to the CA so the appropriate identity is created. About Auto-enrollment Server 13

14 Auto-enrollment decision procedure When the auto-enrollment/recovery request is sent from Security Provider to Auto-enrollment Server, Auto-enrollment Server sends one of the following three types of responses to Security Provider: Approval response A response that includes an authorization code and reference number Security Provider can use to communicate with the CA, and enroll/recover the user or computer. The response also indicates the validity period of these activation codes and whether an enrollment or recovery should be performed. Queued response A response which indicates that the request has been queued for administrative approval. Rejection response A response that includes an error code and reason indicating why the auto-enrollment/recovery cannot occur. Once Security Provider has the approval response, communication with Auto-enrollment Server is complete. The enrollment or recovery is then performed through direct communication with the CA. Enrollment and recovery queues for administrator approval When an auto-enrollment request is sent from Security Provider to Auto-enrollment Server, Auto-enrollment Server can be configured to automatically process the request immediately or queue the enrollment request. Queuing is an optional feature and occurs when an enrollment request waits at Auto-enrollment Server for approval by an administrator. Refer to the chapter Configuring queuing on page 101 for further information on configuring queuing. When an auto-recovery request is sent from Security Provider to Auto-enrollment Server, Auto-enrollment Server can be configured to automatically process the request immediately, queue the recovery request, or reject the request immediately. For further information on what triggers an auto-recovery request, refer to the Entrust Entelligence Security Provider for Windows Administration Guide. When queuing is available, all auto-recovery requests are placed in the queue and the administrator will decide if an auto-recovery should be granted or denied. When queuing is not available for an administrator, the following automatic auto-recoveries will be granted or denied: Granted when the signing certificate is expired when the user is in the Key Recovery state at the CA 14 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

15 Denied when the signing certificate is revoked when updates are not allowed at the CA for this user When an auto-recovery is denied, Auto-enrollment Server returns an error to Security Provider. When the error message displays to the end user, explaining that the auto-recovery attempt failed, the user must inform their administrator that a recovery is required. To enable key recovery for the user, the administrator has to set the user for Key Recovery at the CA. This switches the user from the Active state into the Key Recovery state at the CA, and an auto-recovery is automatically granted by Auto-enrollment Server. About Auto-enrollment Server 15

16 How the distinguished name (DN) is created Auto-enrollment Server may create a distinguished name (DN) for the user or computer if a DN does not already exist in the directory. The default behavior of the DN builder implementation in the Auto-enrollment Server is to take the user or computer name and the domain name to create a DN for this user or computer. If the DN already exists in the directory, most likely when Active Directory is used, it will not be created. If the DN does not already exist in the directory, the DN is added. When the DN is created for a user or computer, it is created differently based upon the directory and whether it is a DN for a user or computer. LDAP Directory The DN of the user or computer is created by using the user or computer name, from the Windows domain name and the DN of the CA. For example, assume the following: computer name is yottbsmith the Windows user is bsmith the domain name is SOMEDOMAIN the complete domain name is SOMEDOMAIN.abc.com the CA DN is ou=someunit, o=abc, c=ca The user being auto-enrolled will have the following default Subject name: cn=bsmith SOMEDOMAIN, ou=someunit, o=abc, c=ca The computer being auto-enrolled will have the following default Subject name: cn=bsmith$ SOMEDOMAIN, ou=someunit, o=abc, c=ca When your organization requires you to create DNs for your users or computers in a different manner than the above example, you may choose to customize the default DN builder implementation. Refer to the section Customizing a user s Distinguished Name (DN) on page 97 for further details. Active Directory The DN for the user or computer in Active Directory is used for the DN in Entrust Managed Services PKI. There are no exceptions and this cannot be customized. Note: This is advanced configuration. Contact your Entrust representative for more information. For example, assume the following: computer name is yottbsmith the Windows user is bsmith the domain name is SOMEDOMAIN 16 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

17 the complete domain name is SOMEDOMAIN.abc.com the machine with Active Directory running on it (the domain controller) has the machine name SOMESERVER the CA DN is cn=someserver, cn=aia, cn=public Key Services, cn=services, cn=configuration, dc=somedomain, dc=abc, dc=com The user being enrolled will have the following default Subject name: cn=bsmith, cn=users, dc=somedomain, dc=abc, dc=com The computer being auto-enrolled will have the following Subject name: cn=yottbsmith, cn=computers, dc=somedomain, dc=abc, dc=com How the subjectaltname is created Auto-enrollment Server may create a subjectaltname for the user or computer. The default behavior of the DN builder implementation in Auto-enrollment Server, is to add a subjectaltname for computers and not to add one for users. Auto-enrollment Server takes the computer name and domain and builds the dnsname, for example, dnsname=computer_name.complete_domain_name. This value is provided when the user or computer is being added to the CA. Entrust Managed Services PKI then adds the dnsname to the SubjectAltName extension of the certificate. For example, assume the following: computer name is yottbsmith the domain name is SOMEDOMAIN the complete domain name is SOMEDOMAIN.abc.com The dnsname of the above example is: dnsname=yottbsmith.somedomain.abc.com Auto-enrollment Server does a dnsname lookup to get the domain. If the dnsname lookup fails, as a backup you can customize the ae-defaults.xml file to build a dnsname. Refer to the section Configuring the DNS name on page 99 for further instructions. How the subjectaltname is created for domain controller certificates Certificates for domain controllers always have extra information added to the subjectaltname. This complies with the Requirements for Domain Controller Certificates from a Third-Party CA (article ID ) as documented by Microsoft. In addition to the dnsname, the directory must include the globally unique identifier (GUID) of the domain controller object. The directory stores the GUID in the About Auto-enrollment Server 17

18 subjectaltname as an Other Name, and it is DER encoded. An example of a subjectaltname with the globally unique identifier (GUID) of the domain controller object in the directory and the Domain Name System (dnsname) is: Other Name: = ac 4b aa d6 5d 4f a9 9c 4c bc b0 6a 65 d9 DNS Name=ComputerNameOfDomainController.SOMEDOMAIN.abc.com When Security Provider creates the auto-enrollment request message for Auto-enrollment Server, it checks if the computer is a domain controller. If yes, it queries the Active Directory and asks for the GUID of the domain controller. Security Provider for Windows will then include the following two pieces of information in the request message to the Auto-enrollment Server: confirmation that the computer is a domain controller the GUID Passing this information in the request message allows Auto-enrollment Server to set extra information in the subjectaltname when necessary. 18 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

19 2 Preparing for installation This chapter describes how to prepare for the Auto-enrollment Server installation. Read this chapter if you are the system administrator installing and configuring machines hosting the Auto-enrollment Server components. This chapter contains the following sections: Planning your installation on page 20 Step 1: Installing the Web Server on page 22 Step 2: Obtaining a Web server certificate on page 24 Step 3: Assigning the certificate to your Web server on page 42 Step 4: Enabling SSL on your Web server on page 51 Step 5: Configuring integrated Windows authentication on page 56 Step 6: Testing the SSL-enabled Web server on page 60 Step 7: Obtaining a certificate for Auto-enrollment Server on page 61 19

20 Planning your installation The following flowchart illustrates the pre-installation steps required for Entrust Managed Services PKI customers installing Auto-enrollment Server. Figure 2: Pre-installation flowchart Attention: Auto-enrollment Server is an add-on that works together with Entrust Entelligence Security Provider (Security Provider). As such, you must already have Security Provider installed at this time. Security Provider and related documentation is available for download from Entrust TrustedCare at 20 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

21 What you should have from Entrust for the pre-installation Ensure you have all the items listed in the table below. If you do not, contact Entrust Managed Services PKI. Table 1: Pre-install check list Item Have it? Your organization s URL to Administration Services, a Web-based application that allows you to create and manage certificates and accounts. Credentials to access Entrust TrustedCare ( which allows you to download purchased software and related documentation Entrust Managed Services PKI Welcome letter. Specifically the name of the Certificate type to select when creating the Web Server certificate account. Pre-installation tasks You must complete the following tasks, in order, prior to installing Auto-enrollment Server. Note: This guide assumes you have already obtained an administrator certificate. If you are an Entrust Managed Services PKI customer, but have not yet created an administrator certificate, see the Administrator Guide under the Resources tab of Step 1: Installing the Web Server on page 22 Step 2: Obtaining a Web server certificate on page 24 Step 3: Assigning the certificate to your Web server on page 42 Step 4: Enabling SSL on your Web server on page 51 Step 5: Configuring integrated Windows authentication on page 56 Step 6: Testing the SSL-enabled Web server on page 60 Step 7: Obtaining a certificate for Auto-enrollment Server on page 61 Preparing for installation 21

22 Step 1: Installing the Web Server If you have not done so already, install the Microsoft IIS Web Server. Note: Ensure you understand all specific security requirements for your product. The following procedure describes the Microsoft IIS Web Server installation on a Windows 2003 server. To install Microsoft IIS Web Server (Windows 2003 Server) 1 Click Start > Control Panel > Add or Remove Programs. The Add or Remove Programs dialog box appears. 2 From the left menu pane, select Add/Remove Windows Components. After a few moments, the Windows Components Wizard dialog box appears. 22 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

23 3 Select Application Server and click Next. Note: This preforms a default installation. For production purposes, you should consult your organization s security policy to determine which components to install. 4 Once complete, click Finish. Preparing for installation 23

24 Step 2: Obtaining a Web server certificate To enable SSL between the Security Provider for Windows client and the Microsoft IIS Web server, a certificate for the Web server is required. If you are deploying Auto-enrollment Server in a multi-domain environment, ensure that each Microsoft IIS Web server is issued a certificate. Complete the following procedures, in order: To log in to Administration Services on page 24 To create a Web server certificate account on page 26 To enroll for the Web server certificate using Security Provider on page 33 To log in to Administration Services 1 Enter the Administration Services URL provided by Entrust Managed Services PKI into a browser. The following page appears. 2 Depending on where you stored your administrator certificate, do one of the following: 24 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

25 if you stored your certificate... in the Entrust desktop security store on your computer within the Windows framework or on a smart card or token. Do this 1 Click Browse to navigate to the location where you stored your administrator digital ID (.epf file) and click Open. The file name and path appear in the Entrust Desktop Security Store File Name field. Select Remember Entrust Desktop Security Store File Name to retain the path. 2 Enter the password you created for your certificate and click Log in. 1 Click the Log in with my Third-Party Security Store link. The Administrator Login - Third-Party Security Store page appears. Note: If logging in with a smart card or token, ensure it is connected to your computer. 2 Click Display certificate list. The Select Certificate dialog box appears listing one or more digital certificates. 3 Select your certificate from the list and click OK. Preparing for installation 25

26 Upon successful login, the following page appears. You successfully logged in to Administration Services. To create a Web server certificate account 1 If you are not already logged in to Administration Services, do so now. See To log in to Administration Services on page 24 for more information. 26 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

27 The main page appears. 2 Click Create Account under Account Tasks in the main pane or under Tasks in the left-hand menu. The initial Create Account page appears. Preparing for installation 27

28 3 From the User Type drop-down list, select Web server. 4 From the Certificate Type drop-down list, select your company s specific certificate type. Consult your Entrust Managed Services PKI Welcome letter for more information. 5 Click Submit. A second Create Account page appears where you provide the Web server name and other information. 28 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

29 6 From the User Information section: a b In the Name field, enter the fully qualified domain name (FQDN) of the server (for example, test.dev.ad.entrust.com). Optionally, enter a description of the Web server certificate account in the Description field. 7 Leave the Notification field empty. 8 From the Group Membership section, select the member option. If no groups are configured, only the default group appears. 9 From the Role section, select End User from the drop-down list. 10 From the Location section, click Select the searchbase and select your company name from the drop-down list (an entry for your organization was created in the directory when you signed up for Entrust Managed Services PKI). This specifies where to add the Web server account in the Administration Services LDAP directory. 11 Click Submit. The Create Account - Complete page appears. Preparing for installation 29

30 12 Securely record the reference number and authorization code. You need these activation codes later during enrollment. 13 Click the name of your Web server certificate in the Name column on the Create Account - Complete page. The Account Details - <Web server name> page appears, where <Web server name> is the FQDN of your Web server. 30 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

31 14 Scroll down and click Edit Account. 15 On the Edit Account - Basic Information page, scroll down to the bottom of the page and click the Edit Advanced Information link. The Edit Account - Advanced Information page appears. Preparing for installation 31

32 16 In the Subject Alternative Naming Information section, enter the following in the DNS field (including the quotation marks): dnsname=<fqdn> where <FQDN> is the fully qualified domain name of your Web server. Note: If your machine is known by multiple names on the network, you can put multiple dnsname entries into the certificate, separated by a space. This allows a single certificate to be used for all instances. 17 Proceed to the below procedure: To enroll for the Web server certificate using Security Provider on page Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

33 To enroll for the Web server certificate using Security Provider 1 Open the Microsoft Management Console: a Click Start > Run. b Enter mmc and click OK. The console appears. 2 From the console, click File > Add/Remove Snap-in. The Add/Remove Snap-in dialog box appears. Preparing for installation 33

34 3 From the Standalone tab, click Add. The Add Standalone Snap-in dialog box appears. 34 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

35 4 Select Entrust Computer Digital ID from the snap-in list, and click Add. The Select Computer dialog box appears. Preparing for installation 35

36 5 Select Local computer and click Finish. 6 Click Close to close the Add Standalone Snap-in dialog box. 7 Click OK on the Add/Remove Snap-in dialog box. The console reappears with the Entrust Computer Digital ID snap-in listed. 36 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

37 8 From the left pane of the console, right-click Entrust Computer Digital ID and select Enroll Computer for Entrust Digital ID. The Welcome to the Enroll Computer for Entrust Digital ID Wizard appears. 9 Click Next. The Specify the activation codes screen appears. Preparing for installation 37

38 10 Enter the reference number and authorization code you obtained in Step 12 on page 30 into the respective fields and click Next. Security Provider contacts the Entrust Managed Services PKI Certification Authority (CA) and, when successful, displays the Confirm Entrust Digital ID Enrollment screen. 38 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

39 11 Click Next. A security warning may appear advising you that you are about to install a certificate issued from the Entrust Managed Services PKI Certification Authority (CA). Preparing for installation 39

40 12 Click Yes to install the certificate. The Completing the Enroll Computer for Entrust Digital ID Wizard screen appears. 40 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

41 13 Click Finish. You successfully enrolled your Web server certificate. Preparing for installation 41

42 Step 3: Assigning the certificate to your Web server Complete the following procedure to assign the SSL certificate to your Web server. To assign the certificate to your Web server 1 Click Start > All Programs > Administrative Tools > Internet Information Services (IIS) Manager. The Internet Information Services (IIS) Manager appears. 2 In the left pane, expand <x> (local computer) and then expand the Web Sites folder, where <x> is the name of your computer. (In the screenshot above, the computer is named TEST.) 3 Right-click the Web site your want to configure for SSL (for example, Default Web Site) and select Properties. The <x> Properties dialog box appears, where <x> is the name of the Web site you selected to configure. 42 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

43 4 Click the Directory Security tab. The Directory Security tab appears. Preparing for installation 43

44 5 In the Secure communications section, click Server Certificate. The Welcome to the Web Server Certificate Wizard wizard appears. 44 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

45 6 Click Next. The Server Certificate screen appears. Preparing for installation 45

46 7 Select Assign an existing certificate and click Next. The Available Certificates screen appears. 46 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

47 8 Select the certificate you created for your Web server and click Next. The SSL Port screen appears. Preparing for installation 47

48 9 Accept the default SSL port 443 and click Next. The Certificate Summary screen appears. 48 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

49 10 Verify everything is correct and click Next. The Completing the Web Server Certificate Wizard screen appears. Preparing for installation 49

50 11 Click Finish. You successfully assigned your SSL Web server certificate in Microsoft IIS. 50 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

51 Step 4: Enabling SSL on your Web server You must enable SSL encryption on your Microsoft IIS Web server to secure the connection between the browser on the machine Security Provider is installed and Auto-enrollment Server. When configuring your Web server, it is advised that you do the following: Enforce 128-bit encryption for browsers accessing your Microsoft IIS Web Server. Enable server SSL authentication so that only the client checks the server s Web certificate but there is no mutual authentication The following procedure describes how to enable SSL on Microsoft IIS Web server 6.0. For all other versions, follow the instructions provided in your Microsoft IIS Web server documentation. Note: Restart your Microsoft IIS Web server after enabling it for SSL. To enable SSL on Microsoft IIS Web Server Click Start > All Programs > Administrative Tools > Internet Information Services (IIS) Manager. The Internet Information Services (IIS) Manager appears. Preparing for installation 51

52 2 In the left pane, expand <x> (local computer) and then expand the Web Sites folder, where <x> is the name of your computer. (In the screenshot above, the computer is named TEST.) 3 Right-click the Web site your want to configure for SSL (for example, Default Web Site) and select Properties. The <x> Properties dialog box appears, where <x> is the name of the Web site you selected to configure. 4 Click the Directory Security tab. The Directory Security tab appears. 52 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

53 5 In the Secure communications section, click Edit. The Secure Communication dialog box appears. Preparing for installation 53

54 6 Select the following: Require secure channel (SSL) Require 128-bit encryption Note: Ensure Ignore client certificates is selected. 7 Click OK. The Directory Security tab reappears. 8 Click OK. The Inheritance Overrides dialog box appears. 54 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

55 9 Click OK. You successfully enabled SSL on your Web server. 10 Restart your Web server: a Click Start > All Programs > Administrative Tools > Services. b From the main pane, select IIS Admin Service. c Click the Restart the service link. Preparing for installation 55

56 Step 5: Configuring integrated Windows authentication After configuring SSL on your Web Server, you must configure integrated Windows authentication. If you do not configure integrated Windows authentication, an Entrust Entelligence Security Provider for Windows user cannot enroll for a certificate. To configure integrated Windows authentication 1 Click Start > All Programs > Administrative Tools > Internet Information Services (IIS) Manager. The Internet Information Services (IIS) Manager appears. 2 In the left pane, expand <x> (local computer) and then expand the Web Sites folder, where <x> is the name of your computer. (In the screenshot above, the computer is named TEST.) 3 Right-click the Web site you configured for SSL (for example, Default Web Site) and select Properties. The <x> Properties dialog box appears, where <x> is the name of the Web site you are configuring for integrated Windows authentication. 56 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

57 4 Click the Directory Security tab. The Directory Security tab appears. Preparing for installation 57

58 5 In the Authentication and access control section, click Edit. The Authentication Methods dialog box appears. 58 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

59 6 In the Authenticated Access section, select Integrated Windows authentication. 7 Click OK to close the Authentication Methods dialog box. 8 Click OK to close the Internet Information Services (IIS) Manager dialog box. You successfully configured integrated Windows authentication. Preparing for installation 59

60 Step 6: Testing the SSL-enabled Web server To ensure that your Web server has been installed and configured properly, test the SSL connection between the Microsoft IIS Web server and a Security Provider for Windows client browser. To test the Web Server From your Security Provider for Windows client, visit your sample Web site using https in the URL instead of http. If your sample Web site appears, your Web server and SSL are running properly. Your Web browser should indicate a secure connection by displaying a solid key or lock icon. Figure 3: SSL lock icon in Internet Explorer Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

61 Step 7: Obtaining a certificate for Auto-enrollment Server Before starting the Auto-enrollment Server installation process, you must obtain a certificate for Auto-enrollment Server. The certificate: verifies signatures establishes SSL connections signs XAP requests for the XAP Server signs files that are used by the User Registration Service (URS) To obtain a certificate for Auto-enrollment server, you must first create an account for the certificate in Administration Services and then enroll for the certificate using Security Provider. Complete the following procedures, in order: To create an account for Auto-enrollment Server in Administration Services on page 61 To enroll for the Auto-enrollment Server certificate on page 65 Note: If you have more than one Auto-enrollment Server machine, it is recommended that you create a separate account for each server. To create an account for Auto-enrollment Server in Administration Services 1 Log in to Administration Services. See To log in to Administration Services on page 24 for more information. Preparing for installation 61

62 The main page appears. 2 Click Create Account under Account Tasks in the main pane or under Tasks in the left-hand menu. The initial Create Account page appears. 62 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

63 3 From the User Type drop-down list, select Person. 4 From the Certificate Type drop-down list, select Enterprise - Admin Services User Registration. 5 Click Submit. A second Create Account page appears where you provide the account name and other information. Preparing for installation 63

64 6 From the User Information section: a b In the First Name field, enter a first name for your Auto-enrollment Server account (for example, AES). In the Last Name field, enter any name (for example; User registration. 7 Leave the and Notification fields empty. 8 From the Group Membership section, select the member option. If no groups are configured, only the default group appears. 9 From the Role section, select the custom role Entrust created for you from the drop-down list (for example; <organization name> User Registration, where <organization name> is the name of your company or organization. 10 From the Location section, click Select the searchbase and select your company name from the drop-down list (an entry for your organization was created in the directory when you signed up for Entrust Managed Services PKI). This specifies where to add the Web server account in the Administration Services LDAP directory. 11 Click Submit. The Create Account - Complete page appears. 64 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

65 12 Securely record the reference number and authorization code. You need these activation codes later during enrollment. 13 Proceed to the below procedure: To enroll for the Auto-enrollment Server certificate on page 65. To enroll for the Auto-enrollment Server certificate 1 Right-click the Security Provider icon ( ) from your task bar, and select Enroll for Entrust Digital ID. The Enroll for Entrust Digital ID Wizard appears. Preparing for installation 65

66 2 Click Next. The Specify your activation codes screen appears. 66 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

67 3 Enter the reference number and authorization code you received in Step 12 on page 65 and click Next. Security Provider attempts to contact the Entrust Managed Services PKI Certification Authority (CA) and, when successful, displays the Confirm Entrust Digital ID Enrollment screen. Preparing for installation 67

68 4 Click Next. The Entrust Security Store Location dialog box appears. 68 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

69 5 Select a location on your machine for the security store, which stores the certificate, and click Next. The default location is C:\Documents and Settings\Administrator\Application Data\Entrust Security Store. Note: If the folder does not exist, a dialog box appears asking if you want to create the location. Select Yes or No. The Entrust Security Store Name dialog box appears. Preparing for installation 69

70 6 Enter a name for your certificate (.epf file) and click Next. (For example, AESUserReg). The Entrust Security Store Password dialog box appears. 70 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

71 7 Enter a password for your certificate, following the rules listed. The red x icons turn to green check marks as you satisfy the requirements. Preparing for installation 71

72 8 Click Finish. The Completing the Enroll for Entrust Digital ID Wizard appears. 9 Click Finish. You successfully obtained a certificate for Auto-enrollment Server and completed all the pre-installation tasks. 72 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

73 3 Installing Auto-enrollment Server This chapter describes the steps required to install and configure the Auto-enrollment Server installation. This chapter includes: Installing Auto-enrollment Server on page 74 Checking the Auto-enrollment Server installation on page 86 What you should have from Entrust for the installation of Auto-enrollment Server Ensure you have all the items listed in the table below. If you do not, contact Entrust Managed Services PKI. Table 2: Install check list Item Have it? Credentials to access Entrust TrustedCare ( which allows you to download purchased software and related documentation The entrust.ini file, which is needed for the installation of Auto-enrollment Server. 73

74 Installing Auto-enrollment Server The InstallShield Auto-enrollment Services Wizard installs and configures all of the Auto-enrollment Server components. Once you have successfully run the wizard, there are no other mandatory configuration steps. Complete the following procedures to download Auto-enrollment Service from Entrust TrustedCare and to install the product: To download Auto-enrollment Server from Entrust TrustedCare on page 74 To install Auto-enrollment Services on page 74 To download Auto-enrollment Server from Entrust TrustedCare 1 Log in to Entrust TrustedCare at with your credentials. 2 Locate the Entrust Authority Auto-enrollment Server product and select the latest release (for example, 7.0). 3 From the Entrust Entelligence Auto-enrollment Server <version> download page page, download the product zip under the Software heading. Attention: Check to see if there are Service Packs and/or Patches first. If there are, download the latest pack or patch instead. 4 Extract the zip file. You successfully downloaded Auto-enrollment Server from Entrust TrustedCare. To install Auto-enrollment Services 1 Open the Auto-enrollment folder you extracted in Step 4 on page 74, and double-click the AES_<version>_win.exe file, where <version> is the most recent version of Auto-enrollment Server (for example, 7.0). The install wizard appears. 74 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

75 2 Click Next. The license agreement screen appears. Installing Auto-enrollment Server 75

76 3 Select I accept the terms of the license agreement and click Next. Note: If you do not accept the terms, you cannot proceed with the installation. The install location screen appears. 76 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

77 4 Browse for a location to install Auto-enrollment Server and click Next. The default location is C:\Program Files\Entrust\AutoEnrollmentServices. The entrust.ini location screen appears. Installing Auto-enrollment Server 77

78 . 5 Specify the name and path to the entrust.ini file, which was provided to you by Entrust representative, and click Next. The Auto-enrollment Server certificate (.epf) location screen appears. 78 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

79 6 Specify the name and path to the Auto-enrollment certificate you created in To enroll for the Auto-enrollment Server certificate on page 65 and click Next. You selected the path in Step 5 on page 69 and the name of the.epf file in the following step (for example: C:\Documents and Settings\Administrator\Application Data\Entrust Security Store\AESUserReg.epf.) The Auto-enrollment Server certificate (.epf) password screen appears. Installing Auto-enrollment Server 79

80 7 Enter the password for the Auto-enrollment Server certificate (.epf) you created in To enroll for the Auto-enrollment Server certificate on page 65 and click Next. You selected this password in Step 7 on page 71. The Web server instance screen appears. 80 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

81 8 Select your Web site from the available list to host your Auto-enrollment Server application, and click Next. The Active Directory for credential storage screen appears. Installing Auto-enrollment Server 81

82 9 Select No and click Next. The Active Directory as certificate repository screen appears. 82 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

83 10 Select No and click Next. The summary screen appears. Installing Auto-enrollment Server 83

84 11 Read the information provided in the summary information page and click Next. After a few moments, the wizard completes the install of Auto-enrollment Server. 84 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

85 12 Click Finish to exit the wizard. You successfully installed Auto-enrollment Server. Installing Auto-enrollment Server 85

86 Checking the Auto-enrollment Server installation After you have completed the Auto-enrollment Server installation, you may want to verify the following: Verify adminservice.log file on page 86 Verify the Web server is passing requests to Auto-enrollment Server on page 86 Verify installation log file on page 87 Verify configuration log file on page 87 Verify adminservice.log file The adminservice.log is the administration log file and displays Auto-enrollment Server information and errors. After installing Auto-enrollment Server, manually restart Auto-enrollment Server in Windows Services. The following event appears in the adminservices.log when services start successfully, without any errors: [ :24: ][DEBUG]UserRegistrationService][URSExtension.ini][][] Completed URS init To verify the adminservice.log file 1 Click Start > All Programs > Administrative Tools > Services. 2 Select Entrust Authority (TM) Auto-enrollment Server from the list of services and click Restart the service. 3 Once restarted, wait a few moments and open the adminservice.log file in a text editor, such as Notepad. The log is located in the following directory <install_directory>\autoenrollmentservices\logs\ where <install_directory> is the location of your Auto-enrollment Server install. By default, the install location is: C:\Program Files\Entrust\. Refer to the section Logging configuration on page 110 for detailed information on the administration log file. Verify the Web server is passing requests to Auto-enrollment Server After you have completed the Auto-enrollment Server installation, you should verify that the Microsoft IIS Web Server is properly passing requests on to the Auto-enrollment Server. 86 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

87 To verify the Microsoft IIS Web Server is passing requests to Auto-enrollment Server 1 Open a browser on the machine with your Web server installed and enter the following URL: where <FQDN> is the fully qualified domain domain of the server (for example, test.dev.ad.entrust.com). The following information should appear: SSL should be enabled an error specifying that a GET request was sent to Auto-enrollment Server Verify installation log file The installation log file can be used for information purposes or to diagnose installation related problems. The installer logs the following information: detects environment information (for example, free space in temp directory) any warnings that were issued and bypassed by the person installing the software actions performed (for example, files copied,.jar files created, and so on) error information InstallShield standard logging information (for example, extracting the JVM, evaluating conditions on whether or not to run an action) Once the installation completes, the installation log file appears in the following location: <install_directory>\autoenrollmentservices\logs\autoenrollments ervices_installer.log Verify configuration log file The configuration log file can be used for information purposes or to diagnose configuration related problems. The configuration logs the following information: auto-detected environment information answers to questions that the person installing the software provided actions performed (for example, files copied, configuration changed, and so on) detailed error information warnings Installing Auto-enrollment Server 87

88 Once the installation completes, the configuration log file appears in the following location: <install_directory>\autoenrollmentservices\logs\autoenrollments ervices_configuration.log 88 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

89 4 Customizing the Auto-enrollment Server You can configure the Auto-enrollment Server by modifying the ae-config.xml and ae-defaults.xml files. Note: For any changes to take effect, you must restart the Entrust Authority Auto-enrollment Service in Windows Services. This chapter describes how to customize Auto-enrollment Server: Customizing the certificate type and user role on page 91 Customizing certificate lifetimes on page 96 Customizing a user s Distinguished Name (DN) on page 97 Customizing a search base for enrolling clients on page 98 Configuring the DNS name on page 99 89

90 What you should have from Entrust for Auto-enrollment Server customizations Ensure you have all the item listed in the table below. If you do not, contact Entrust Managed Services PKI. Table 3: Auto-enrollment Server check list Item Have it? Entrust Managed Services PKI Welcome letter. Specifically the names of your certificate type for users and computers roles for users and computers search base for enrolling clients 90 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

91 Customizing the certificate type and user role Auto-enrollment Server settings can be used to choose a specific role and certificate type for users or computers. You can choose to keep the defaults or configure new defaults for your users and computers that are auto-enrolling. Note: If you need to change a user or computer s certificate type or role after they auto-enrolled and are in the added state in Administration Services, you must manually configure a new certificate type and role. Configuring a default certificate type Auto-enrollment Server uses a default certificate type for users and computers. <User>ent_default</User> The default certificate type for users. <Machine>ent_default</Machine> The default certificate type for computers. To configure a new default certificate type, complete the following procedure. To configure a new default certificate type 1 Open the ae-defaults.xml file in a text editor, such as Notepad: <install_location>\autoenrollmentservices\config <install_location> is the location of the Auto-enrollment Server install. By default, the install location is C:\Program Files\Entrust. 2 Locate the following section of code: <!-- Default cert types for user or computer auto-enrollments, for clients that send no <CertTypeInfo> in their auto-enrollment request --> <DefaultCertType> <User>ent_default</User> <Machine>ent_default</Machine> </DefaultCertType> 3 Replace one or both of the default certificate type settings with the certificate types listed in your Entrust Managed Services PKI Welcome letter: <User>ent_default</User> <Machine>ent_default</Machine> Some examples of valid certificate types are: Customizing the Auto-enrollment Server 91

92 ent_twokeypair two key pair user (encryption and verification) ent_nonrepud three key pair user with non-repudiation key pair (encryption, verification, and non-repudiation) ent_efs three key pair user with EFS key pair (encryption, verification, and encryption file system (EFS)) ent_nonrepud_and_efs four key pair user with Nonrepudiation and EFS Key Pairs (encryption, verification, nonrepudiation, and EFS) ent_skp_dualusage one dual usage key pair (dual usage) 4 Save the file. 5 Restart Auto-enrollment Server services in Windows Services. Configuring a default User Role The Auto-enrollment Server has a default role for your users and computers. <User>End User</User> The default user role. <Machine>End User</Machine> The default computer role. To configure a new default role, complete the following procedure. Note: The administrator must have permission to administer the roles that you configure. To configure a new default role 1 Open the ae-defaults.xml file in a text editor, such as Notepad: <install_location>\autoenrollmentservices\config <install_location> is the location of the Auto-enrollment Server install. By default, the install location is C:\Program Files\Entrust. 2 Locate the following section of code: <!-- Default roles for user or computer auto-enrollments, for clients that send no <CertTypeInfo> in their auto-enrollment request --> <DefaultRole> <User>End User</User> <Machine>End User</Machine> </DefaultRole> 92 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

93 3 Replace the default role settings with the roles listed in your Entrust Managed Services PKI Welcome letter: <User>End User</User> and/or <Machine>End User</Machine> Some examples of valid roles are: Security Officer Administrator Directory Administrator Auditor Self-Administration Server Administrator End User Note: Entrust may have created some custom roles for you. If you are unaware of the custom roles assigned, contact your Entrust representative. 4 Save the file. 5 Restart Auto-enrollment Server services in Windows Services. Configuring the client information setting Auto-enrollment Server has a client information setting that controls the assignment of the certificate type and user role when Security Provider auto-enrolls/recovers. The client information setting is an arbitrary string that must match the string that is sent by Security Provider. The arbitrary string is configured in the Windows Registry on the machine that has Security Provider installed: AutoEnrollUserDigitalIDType arbitrary string used for user auto-enrollment/recovery AutoEnrollMachineDigitalIDType arbitrary string used for computer auto-enrollment/recovery Auto-enrollment Server takes this string and assigns a certificate type and role to Security Provider. The Auto-enrollment Server administrator must be allowed to administer users that have these roles, otherwise the enrollment will fail. For example, if the user is assigned the Security Officer role and the Auto-enrollment administrator cannot administer users with the Security Officer role, the enrollment will fail. Auto-enrollment Server has a client information string that you can configure for users and computers. To configure a new client string, complete the following procedure. Customizing the Auto-enrollment Server 93

94 To configure a new client string 1 Open the ae-defaults.xml file in a text editor, such as Notepad: <install_location>\autoenrollmentservices\config <install_location> is the location of the Auto-enrollment Server install. By default, the install location is C:\Program Files\Entrust. 2 Locate the following section of code: <!-- CertTypeInfo controls the assignment of certificate type and user role when a client enrolls. Edit as required. ClientInfo strings are arbitrary but must match the string that the client sends. If a ClientInfo string is repeated, AE uses the first encountered. AE server assigns a <CertType> and <Role> to a client that sends a particular <ClientInfo> string. The AE Server admin must be allowed to administer users that have these roles; otherwise enrollment will fail. --> <CertTypeInfo> <ClientRequest> <ClientInfo>some_clients_send_this_string</ClientInfo> <CertType>ent_default</CertType> <Role>End User</Role> </ClientRequest> <ClientRequest> <ClientInfo>other_clients_send_this_different_string</ClientInfo> <CertType>ent_skp_dualusage</CertType> <Role>Server Login</Role> </ClientRequest> </CertTypeInfo> Security Provider sends a client request to Auto-enrollment Server. The request contains an arbitrary string that was configured in the AutoEnrollUserDigitalIDType Windows registry on the machine that has Security Provider installed. In this case, the Security Provider registry setting is AutoEnrollUserDigitalIDType=some_clients_send_this_string Auto-enrollment Server looks to see if this matches the arbitrary string in the <ClientInfo> tags. In this code example, the <ClientInfo> tags in the do contain the same string: <ClientInfo>some_clients_send_this_string</ClientInfo> 3 Change the <CertType> and <Role> as required. 94 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

95 Auto-enrollment Server reads the <CertType> and <Role> tags to determine which certificate type and role to use for the auto-enrollment. In this code example, the <CertType> is ent-default and the <Role> is End User. Note: If the string sent in the Security Provider request does not match a string in any of the <ClientInfo> tags, an error is logged and returned to the client. The default certificate type and role are used when the client does not send any <ClientInfo> string at all, or no <ClientTypeInfo> is configured at the server. 4 Save the file. 5 Restart Auto-enrollment Server services in Windows Services. Customizing the Auto-enrollment Server 95

96 Customizing certificate lifetimes You can configure the ae-defaults.xml file to set certificate lifetimes for users or computers. You can choose to keep the defaults or configure new defaults for your users and computers that are auto-enrolling. Note: The certificate lifetimes settings in the <CertificatePolicy> section override the default certificate lifetime settings in the CA. To use the default settings, delete or comment out the settings in the <CertificatePolicy> section. To configure the certificate lifetimes, complete the following procedure. To configure certificate lifetimes 1 Open the ae-defaults.xml file in a text editor, such as Notepad: <install_location>\autoenrollmentservices\config <install_location> is the location of the Auto-enrollment Server install. By default, the install location is C:\Program Files\Entrust. 2 Locate the following section of code: <!-- Example of a CertificatePolicy. Edit as required, or remove it to get default policy associated with the user Role. --> <CertificatePolicy> <EncLifetime>36</EncLifetime> <VerLifetime>36</VerLifetime> <SignLifePercentage>70</SignLifePercentage> </CertificatePolicy> 3 To change the lifetime (in months) of encryption certificates, change the <EncLifetime> value. You can specify a value between 2 and 420 months (35 years). 4 To change the lifetime (in months) of vertification certificates, change the <VerLifetime> value. You can specify a value between 2 and 420 months (35 years). 5 To change the percentage of the signing private key lifetime, which determines when a user s key pair requires updating, change the <SignLifePercentage> value. You can specify a value from 1 to 100 (percent). 6 Save the file. 7 Restart Auto-enrollment Server services in Windows Services. 96 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

97 Customizing a user s Distinguished Name (DN) Auto-enrollment Server uses the DN builder implementation (DistinguishedNameBuilderImpl) by default, to automatically create a user s or computer s distinguished name (DN), common name (CN), and surname from the information in the Security Provider request. If you are using a Microsoft Active Directory as your certificate repository, the default DistinguishedNameBuilderImpl attempts to read the client s distinguished name (DN), common name (CN), surname, address, and UPN from that directory. The default DistinguishedNameBuilderImpl builds a distinguished name (DN) for Security Provider by using the following: common name (cn) client s authenticated Windows account name surname Windows domain search bases uses the search bases that are configured in the ae-defaults.xml file The default also sets a dnsname as a subjectaltname extension for computer enrollments. In addition, it sets an othername as a subjectaltname extension if the client machine is a domain controller. The othername has the domain controller GUID. The default does not set a subjectaltname extension for user enrollments, unless you are using Active Directory as the certificate repository. However, there is sample code that you can use to customize the DN builder implementation to set a subjectaltname. If you are using Active Directory as the repository for user or machine enrollments, the default DistinguishedNameBuilderImpl reads the client s address and UPN from the directory and sets them into the subjectaltname extension. Note: If you need to change a user or computer s DN after they have auto-enrolled and are in the Added state in Administration Services, you must manually configure a new DN. Refer to Appendix A Writing your own DN Builder implementation code on page 131 for further information about the code that you can use to create your own DN builder implementation. Customizing the Auto-enrollment Server 97

98 Customizing a search base for enrolling clients Security Provider is enrolled on the search bases that are set for users or machines in the <DNBuilderSearchBase> setting in the ae-defaults.xml file. If no search bases are provided, the client is enrolled on the search base where the Auto-enrollment Server administrator resides. However, with Active Directory the client s account is already in the directory and the enrollment uses that DN, instead of the <DNBuilderSearchBase> setting. Consult your Entrust Managed Services PKI Welcome letter for more information. Note: If you need to change a user or computer s search base after they have auto-enrolled and are in the Added state in Administration Services, you must manually configure a new search base. Complete the following procedure to configure the search base value. To configure the search base value 1 Open the ae-defaults.xml file in a text editor, such as Notepad: <install_location>\autoenrollmentservices\config <install_location> is the location of the Auto-enrollment Server install. By default, the install location is C:\Program Files\Entrust. 2 Locate the following section of code: <!-- The search base under which clients will be enrolled. This is optional. If you omit it, the CA search base will be used. --> <DNBuilderSearchBase> <User></User> <Machine></Machine> </DNBuilderSearchBase> 3 To configure a search base for users, add your search base value to the <User> setting. computers, add a search base value to the <Machine> setting. Attention: The <User> and <Machine> settings are not used if Active Directory is the certificate repository. These settings may be used if Active Directory is the Windows account repository. 4 Save the file. 5 Restart Auto-enrollment Server services in Windows Services. 98 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

99 Configuring the DNS name Auto-enrollment Server attempts to locate a Domain Name System (dnsname) for the auto-enrollment. If the dnsname lookup fails, as a back up you can configure a setting so that Auto-enrollment Server knows what dnsname to assign to authenticated clients from a particular Windows domain. Complete the following procedure to configure the dnsname. To configure the DNS name 1 Open the ae-defaults.xml file in a text editor, such as Notepad: <install_location>\autoenrollmentservices\config <install_location> is the location of the Auto-enrollment Server install. By default, the install location is C:\Program Files\Entrust. 2 Locate the following section of code: <!-- List of accepted clients --> <DomainList> <Domain> <Windows>Your_Windows_domain_name</Windows> <DNS>Your_DNS_name</DNS> </Domain> </DomainList> 3 Change the value in the <DNS>Your_DNS_name</DNS> setting to reflect your organization s dnsname domain value. In the example below, the domain is example_hq but the dnsname is example.com. The ae-defaults.xml file can be customized to always map example_hq to example.com: <!-- List of accepted clients --> <DomainList> <Domain> <Windows>example_hq</Windows> <DNS>example.com</DNS> </Domain> </DomainList> 4 Save the file. 5 Restart Auto-enrollment Server services in Windows Services. Customizing the Auto-enrollment Server 99

100 100 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

101 5 Configuring queuing Queuing is an optional feature of Auto-enrollment Server. The main purpose of queuing is to allow an Auto-enrollment Server administrator to approve or reject auto-enrollment/recovery requests. If you opted for the queuing feature, it was automatically added by Entrust as a permission to the role you selected when you created the Auto-enrollment Server certificate ( Step 7: Obtaining a certificate for Auto-enrollment Server on page 61). If you desire this feature at a later time, contact your Entrust representative. When your organization wants to use queuing, you must configure all of the following: Enabling queuing in Auto-enrollment Server on page 102 Approving or rejecting requests in Administration Services on page

102 Enabling queuing in Auto-enrollment Server To enable queuing in Auto-enrollment Server, you must configure the ae-defaults.xml file. use the following two procedures to configure the Auto-enrollment Server s ae-defaults.xml file: Configuring the ae-defaults.xml file to queue requests on page 102 Configuring the queuing monitor on page 103 Configuring the ae-defaults.xml file to queue requests The default, queuing is disabled (NoQueue) in the ae-defaults.xml file. To enable queuing, you must change the NoQueue value to Force. Note: If Entrust has not configured the Auto-enrollment Services account role with the queue permission, setting the <Enroll> or <Recover> settings to Force will fail. Complete the following procedure to enable queuing in the ae-defaults.xml file. To enable queuing in the ae-defaults.xml file 1 On the machine with Auto-enrollment Server installed, open the ae-defaults.xml file in a text editor: <install_location>\autoenrollmentservices\config <install_location> is the location of the Auto-enrollment Server install. By default, the install location is C:\Program Files\Entrust. 2 Locate the following section of code in the ae-defaults.xml file: <!-- "Force"=queue the operation (fails if the URS admin's user role does not permit queuing) --> <!-- "NoQueue"=do not queue (fails if the URS admin's user role requires queuing) --> <QueueMode> <Enroll>NoQueue</Enroll> <Recover>NoQueue</Recover> </QueueMode> 3 Change the NoQueue value to Force in the <Enroll>NoQueue</Enroll> and/or <Recover>NoQueue</Recover> settings. 4 Save the changes to the ae-default.xml file. 5 Restart Auto-enrollment Server services in Windows Services for the changes to take effect: 102 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

103 a b Click Start > All Programs > Administrative Tools > Services. Select Entrust Authority (TM) Auto-enrollment Server from the list of services and click the Restart the service link. You successfully enabled queuing in the ae-defaults.xml file. Configuring the queuing monitor Auto-enrollment Server has a queuing monitor that fetches a list of queued requests. Auto-enrollment Server caches this list and uses it to determine if there have been any previous cancelled requests. Since identical requests are allowed to be queued after the administrator has cancelled the initial identical request, the queuing monitor solves this by preventing repeated identical requests from being forwarded. Requests that are queued are logged into the adminservices.log file when Auto-enrollment Server starts up or whenever the Auto-enrollment Server s queued request list cache is refreshed. The queued request list is cached for a configurable time interval, which is set using the <QueueRefreshTime> setting in the ae-defaults.xml file. The default <QueueRefreshTime> time interval is 1800 seconds (30 minutes). You cannot set the time interval to less than 10 seconds, as it impacts performance. If you attempt to do so, Auto-enrollment Server uses 10 seconds as the default in order to avoid a decline in performance. It is important that you configure the queued list to be fetched before Security Provider repeats the request. Security Provider uses the following settings to determine the interval at which it sends the auto-enrollment/recovery requests: CertUpdateInterval: The interval specified for the Digital ID Monitor, which requests the auto-enrollment/recovery for user digital IDs. MachineCertUpdateInterval. The interval specified for the Entrust Entelligence Machine Digital ID Service (EEMDIS), which requests the auto-enrollment/recovery for computer digital IDs. By default, the CertUpdateInterval and MachinCertUpdateInterval both perform auto-enrollment/recovery requests every 12 hours. These defaults are configurable in the Microsoft Windows Registry on the machine in which the Security Provider client is installed. See the Entrust Entelligence Security Provider for Windows Administration Guide for more information. Complete the following procedure if you want to change the default queue time interval. To configure the queuing monitor 1 On the machine with Auto-enrollment Server installed, open the ae-defaults.xml file in a text editor: <install_location>\autoenrollmentservices\config Configuring queuing 103

104 where <install_location> is the location of the Auto-enrollment Server install. By default, the install location is C:\Program Files\Entrust. 2 Locate the following section of code in the ae-defaults.xml file: <!-- The time interval at which AE Server fetches the request queue from the Security Manager (seconds). It must be smaller than the time between repeated requests from any one particular client. The ESP client default is 12 hours. --> <!-- This setting is not used unless QueueMode is set to 'Force'. --> <QueueRefreshTime>1800</QueueRefreshTime> 3 Change the QueueRefreshTime value to a value of your choosing, in seconds, in the <QueueValueRefreshTime>1800</QueueRefreshTime> setting. Attention: If you configure the <QueueRefreshTime> to fetch the list of queued requests too frequently, this will degrade the performance of your Auto-enrollment Server. 4 Save the changes to the ae-default.xml file. 5 Restart Auto-enrollment Server services in Windows Services for the changes to take effect: a Click Start > All Programs > Administrative Tools > Services. b Select Entrust Authority (TM) Auto-enrollment Server from the list of services and click the Restart the service link. You successfully configured the queuing monitor in the ae-defaults.xml file. 104 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

105 Approving or rejecting requests in Administration Services Once you have logged in to Administration Services using the Administrator Login, you can approve, cancel, or cancel and delete pending auto-enrollment/recovery requests. When an administrator Approves an auto-enrollment/recovery request, the request is submitted for processing. When the administrator s approval completes, authorization codes are sent to the Security Provider for Windows client. If the queue request requires approval by several administrators, the request remains queued until all administrators have approved the request. Cancels a queued auto-enrollment/recovery request, an identical request cannot be queued. Cancels and deletes a queued auto-enrollment/recovery request, a new identical request can be queued. To approve, cancel, or cancel and delete pending auto-enrollment/recovery request 1 Log in to Administration Services. See To log in to Administration Services on page 24 for more information Configuring queuing 105

106 the following page appears. 2 Click Approve Pending Requests in the left pane under Tasks, or from the main pain under Request Tasks. The Approve Pending Requests page displays, with a list of all requests that are currently in the queue. 3 To view detailed information on a request, click the request name. A new browser window opens with a list of relevant information on the request. 4 Select an auto-enrollment/recover request that you want to process. 5 Select one of the following actions for the chosen request: Approve Approving a request allows it to be submitted for processing. If the request needs approval by more than one administrator, the request is submitted for processing only after all administrators have approved the request. Cancel Cancelling a request removes the request from all Approve Pending Request pages. An identical request cannot be queued. Cancel and Delete 106 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

107 Cancel and Delete removes the request from all request pages and all queues. An identical request can be queued. You may also want to view the List Requests page. This page allows you to quickly view a list of all approved, cancelled, completed, or expired requests, up to the maximum number allowed by the system. To display information on a specific request, click the request name and a list of relevant information will be displayed. Note: When an administrator deletes a request (Cancel and Delete), these deleted requests are removed from the List Requests page. Configuring queuing 107

108 108 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

109 6 Troubleshooting This section includes troubleshooting information and information on using the Auto-enrollment Server log service. Logging configuration on page 110 Time synchronization on page 115 Error messages on page

110 Logging configuration The Auto-enrollment Server uses the Entrust Common Logger which is found in the entlogger.jar file. The Auto-enrollment Server s logging is configured in the Logging parameters section of the ae-config.xml file: <!-- Logging parameters --> <parameter name="log.level" value="trace"/> <parameter name="log.file" value="c:\program Files\Entrust\AutoEnrollmentServices\logs\adminservices.log"/> <parameter name="log.file.size" value=" "/> <parameter name="log.file.num" value="10"/> <parameter name="log.file.maxmessagelength" value="1000"/> Attention: Any time you make a change to the ae-config.xml file, you must restart Auto-enrollment Server in Windows Services. Setting the log level The log contents file adminservices.log is created according to the log level set in the ae-config.xml file. Entrust Common Logger supports the following log levels: TRACE DEBUG INFO WARNING ERROR ALERT FATAL Successful enrollments or recoveries are logged at the TRACE, DEBUG, and INFO log levels. Failures of enrollments or recoveries are logged at the TRACE, DEBUG, INFO, and ERROR levels. By default, the log level is set to TRACE. Complete the following procedure to set the log level. 110 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

111 To set the log level 1 On the machine with Auto-enrollment Server installed, open the ae-config.xml file in a text editor: <install_location>\autoenrollmentservices\config where <install_location> is the location of the Auto-enrollment Server install. By default, the install location is C:\Program Files\Entrust. 2 Locate the following section of code in the ae-defaults.xml file: <!-- Logging parameters --> <parameter name="log.level" value="trace"/> <parameter name="log.file" value="c:\program Files\Entrust\AutoEnrollmentServices\logs\adminservices.log"/> <parameter name="log.file.size" value=" "/> <parameter name="log.file.num" value="10"/> <parameter name="log.file.maxmessagelength" value="1000"/> 3 Change the value parameter in the following line to the log level of your choice: <parameter name="log.level" value="trace"/> Log levels include: TRACE DEBUG INFO WARNING ERROR ALERT FATAL 4 Save the file. 5 Restart Auto-enrollment Server in Windows Services. Setting the log file location The adminservices.log file location is set in the ae-config.xml file under the log.file parameter name. The log file location is specified by the full path and name of the log file. By default, the log file is installed in this location: C:\Program Files\Entrust\AutoEnrollmentServices\logs\adminservices.log Complete the following procedure to change the file location of the adminservices.log file. Troubleshooting 111

112 To change the location of the adminservices.log file 1 On the machine with Auto-enrollment Server installed, open the ae-config.xml file in a text editor: <install_location>\autoenrollmentservices\config where <install_location> is the location of the Auto-enrollment Server install. By default, the install location is C:\Program Files\Entrust. 2 Locate the following section of code in the ae-config.xml file: <!-- Logging parameters --> <parameter name="log.level" value="trace"/> <parameter name="log.file" value="c:\program Files\Entrust\AutoEnrollmentServices\logs\adminservices.log"/> <parameter name="log.file.size" value=" "/> <parameter name="log.file.num" value="10"/> <parameter name="log.file.maxmessagelength" value="1000"/> 3 From the log.file parameter, change the value representing the file location to the full file path of your choice: <parameter name="log.file" value="c:\program Files\Entrust\AutoEnrollmentServices\logs\adminservices.log" /> 4 Save the file. 5 Restart Auto-enrollment Server in Windows Services. Setting the maximum log file size The maximum log file size is set in the ae-config.xml file, under the log.file.size parameter name. The maximum log file size is specified in bytes. By default, the maximum log file size is bytes. Complete the following procedure to set the maximum log file size. To set the maximum log file size 1 On the machine with Auto-enrollment Server installed, open the ae-config.xml file in a text editor: <install_location>\autoenrollmentservices\config where <install_location> is the location of the Auto-enrollment Server install. By default, the install location is C:\Program Files\Entrust. 2 Locate the following section of code in the ae-config.xml file: <!-- Logging parameters --> 112 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

113 <parameter name="log.level" value="trace"/> <parameter name="log.file" value="c:\program Files\Entrust\AutoEnrollmentServices\logs\adminservices.log"/> <parameter name="log.file.size" value=" "/> <parameter name="log.file.num" value="10"/> <parameter name="log.file.maxmessagelength" value="1000"/> 3 From the log.file.size parameter, change the value to the log file size of your choice, in bytes: <parameter name="log.file.size" value=" "/> 4 Save the file. 5 Restart Auto-enrollment Server in Windows Services. Setting the number of backup log files allowed The maximum number of backup log files allowed is set in the ae-config.xml file, under the log.file.num parameter name. By default, the maximum number of backup log files allowed is 10. When the adminservices.log is full a new log file is created. The next file is appended with the number 1. For example, adminservices.log.1. As each file becomes full, the number is incremented by 1. For example, when the adminservices.log.1 file is full, the adminservices.log.2 file is created. These files will be created until the maximum number of backup log files allowed is reached. When the maximum number of backup log files is reached, the previous files will be overwritten, beginning with the adminservices.log file. Complete the following procedure to set the number of backup log files allowed. To set the number of backup files allowed 1 On the machine with Auto-enrollment Server installed, open the ae-config.xml file in a text editor: <install_location>\autoenrollmentservices\config where <install_location> is the location of the Auto-enrollment Server install. By default, the install location is C:\Program Files\Entrust. 2 Locate the following section of code in the ae-config.xml file: <!-- Logging parameters --> <parameter name="log.level" value="trace"/> <parameter name="log.file" value="c:\program Files\Entrust\AutoEnrollmentServices\logs\adminservices.log"/> <parameter name="log.file.size" value=" "/> Troubleshooting 113

114 <parameter name="log.file.num" value="10"/> <parameter name="log.file.maxmessagelength" value="1000"/> 3 From the log.file.num parameter, change the value to a value of your choice: <parameter name="log.file.num" value="10"/> 4 Save the file. 5 Restart Auto-enrollment Server in Windows Services. Setting the maximum message length The maximum message length for a log message is set in the ae-config.xml file, under the log.file.maxmessagelength parameter name. By default, the maximum message length for a log message is 1000 characters. Complete the following procedure to set the maximum message length. To set the maximum message length 1 On the machine with Auto-enrollment Server installed, open the ae-config.xml file in a text editor: <install_location>\autoenrollmentservices\config where <install_location> is the location of the Auto-enrollment Server install. By default, the install location is C:\Program Files\Entrust. 2 Locate the following section of code in the ae-config.xml file: <!-- Logging parameters --> <parameter name="log.level" value="trace"/> <parameter name="log.file" value="c:\program Files\Entrust\AutoEnrollmentServices\logs\adminservices.log"/> <parameter name="log.file.size" value=" "/> <parameter name="log.file.num" value="10"/> <parameter name="log.file.maxmessagelength" value="1000"/> 3 From the log.file.maxmessagelength parameter, change the value to a value of your choice: <parameter name="log.file.maxmessagelength" value="1000"/> 4 Save the file. 5 Restart Auto-enrollment Server in Windows Services. 114 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

115 Time synchronization The time on the computer on which the Auto-enrollment Server runs must be synchronized with the certification authority (CA) time. This allows replay attacks to be detected on messages sent from the Auto-enrollment Server to the CA using the XAP protocol. For this reason, the Auto-enrollment Server will not start properly if the time difference is greater than five minutes. The error appears in the adminservices.log file as follows: [ :41: ][DEBUG][UserRegistrationService][URSExtension.ini t][][] com.entrust.adminservices.urs.ursexception: (URS0100) An error occurred in the User Registration Service. Caused by: com.entrust.adminservices.urs.autoenroll.autoenrollexception: (AES0103) Failed to get an administration services context for communicating with the CA. Caused by: com.entrust.adminservices.toolkit.internal.xap.xapexception: (atkxap.xap.2006) The XAP message has an expired timestamp. The message contained a timestamp that was outside the server's acceptance window. Make sure that the source used to obtain message timestamps is synchronized with the server's time. Synchronize the Auto-enrollment Server machine time setting to within a five minute window of the Entrust CA. Contact Entrust for more information. Troubleshooting 115

116 Error messages For a complete list of Auto-enrollment Server errors and possible solutions, refer to the Entrust Authority Auto-enrollment Server Error Message document, available for download from Entrust TrustedCare at Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

117 Glossary Glossary of terms Term activation codes Active user Added user administrator ALERT attribute Definition The reference number and authorization code that are generated when an administrator adds or recovers a user using Administration Services, or when users add or recover themselves using Entrust Entelligence Security Provider for Windows with the Auto-enrollment Server. An end user who has created an Entrust digital ID and is ready to use their Entrust desktop application. When you create accounts for users, activation codes are generated. These activation codes are used by end users to enroll their certificates. Once users enroll, they are considered active or activated users. An end user who has had their account created by an Administrator in Administration Services, but who has not yet enrolled for their certificate An Administrator (with an uppercase a ) is a trusted person who uses Administration Services to create user accounts and to do other frequent operations, such as deactivate users, revoke a user s keys, set up users for key recovery, and create new encryption key pairs for users. An Entrust error level that logs messages regarding conditions you need to correct immediately. For example, a corrupt system database. A piece of information that describes an aspect of a directory entry. Entries are the building blocks of the Directory. Each attribute consists of an attribute type and at least one attribute value. For example, one attribute type is cn, and its attribute value could be Alice. 117

118 Term authentication authorize authorization code CA CA certificate CA issuer CA signing key pair CA signing private key CA verification public key cache CAPI Definition The process of proving your identity. In Entrust, authentication works through a password-protected encrypted file, called the Entrust digital ID. This digital ID contains a user s identity ( Distinguished Name (DN) ), the decryption private key, any signing keys, and the CA signing keys. When users log into an Entrust desktop application, they choose their Entrust digital ID and enter their password. This process verifies their identity and allows them to access their private data. The act of approving an administrative sensitive operation (for example, creating a digital ID ), by entering the password of an administrator. An alphanumerical code (for example, CMTJ-8VOR-VFNS) generated when an administrative user creates a new user or recovers an existing user, required along with its corresponding reference number. Authorization codes can only be used once. See Certification Authority (CA) A certificate issued by a Certification Authority (CA) containing the CA verification public key. The Web server and a user s browser must import this certificate and use the verification public key contained within it to verify the CA signature on Web server and browser certificates when setting up a secure session (see Secure Sockets Layer (SSL) ). The entity (often the Certification Authority (CA) itself) that distributes the CA certificate. The key pair of the Certification Authority (CA). It consists of the CA signing private key and CA verification public key. The private key portion of the CA signing key pair. The Certification Authority (CA) signing private key is used to digitally sign client (for example, browser and Web server) certificates. The signature on these certificates can be verified with the CA verification public key. A CA signs all certificates it issues using the CA signing key. The public key portion of the CA signing key pair. It verifies client certificates that have been signed by the CA signing private key. A temporary area for information storage, such as user information, used to improve system performance. See CryptoAPI. 118 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

119 Term certificate certificate category certificate expiry certificate revocation Certificate Revocation List (CRL) certificate store certificate type certificate validation Certification Authority (CA) client (application) Definition A collection of publicly available information in standard format about an entity that is digitally signed by the Certification Authority (CA). A certificate is used to uniquely identify people and resources over networks such as the Internet. Certificates also enable secure, confidential communication between two parties (see Secure Sockets Layer (SSL) ). A certificate typically includes a variety of information pertaining to its owner and to the CA that issued it, including the name of the holder and other holder identification information (for example, the URL of the Web server using the certificate or an address), the holder s public key, the name of the Certification Authority that issued the certificate, a serial number, and the validity period (or lifetime) of the certificate (a start and an end date). The CA issues all certificates according to the format and structure of the X.509 version 3 standard. A group to which a certificate belongs (for example, Enterprise, VPN, Web, policy, and so on) that indicates its purpose. Each category can contain one or more certificate types (see certificate type ). The date after which a user s certificate should no longer be trusted. See revoking certificates A signed and timestamped certificate containing the serial numbers of public key certificates that have been revoked, and a reason for each revocation. Contains user and machine certificates, and keeps track of the Cryptographic Service Provider (CSP) associated with each certificate. The information that determines how a certificate is customized when issued. The process of verifying the trustworthiness of a certificate by checking that the certificate has not been tampered with, is not revoked, and was issued by a Certification Authority (CA) you trust. The CA ensures the trustworthiness of electronic identities. It issues electronic identities in the form of public key certificates, policy certificates, cross-certificates, certificate revocation lists (see Certificate Revocation List (CRL) ), and Authority Revocation Lists (ARL), and signs the certificates with its signing key to ensure the integrity of the electronic identity. See certificate. An application running as a desktop agent that receives information from a server application and requests a service provided by the server application. For example, the Entrust Entelligence Security Provider for Windows client. Glossary of terms 119

120 Term client authentication computer credentials credentials file CRL CRL check CryptoAPI Cryptographic Service Provider (CSP) CSP CSP type database Definition The authentication whereby users prove their identity to the server, using, (for example) Entrust Entelligence Security Provider for Windows. A Security Provider for Windows client that is a machine with no end user. This machine can communicate with the Auto-enrollment Server to enroll or recover an Entrust digital ID for computer. 1) A set of data in a generic Public Key Infrastructure (PKI) that defines an entity and contains a user's critical information, or keying material. An Entrust digital ID is a specific type of credentials. 2) A set of data (for example, a username and password or certificate) that defines a user to the system. A set of critical information about a user of a PKI. In Entrust Managed Services PKI, a user's credentials file is usually stored in a.epf file. The Server Login credentials file is a.ual file. See Certificate Revocation List (CRL). The inspection of a Certificate Revocation List (CRL) (accessed from the directory ) by another user to check the trustworthiness of the certificates of the users they intend on encrypting files for. Cryptographic Application Programming Interface or CAPI. The Microsoft Windows API that provides PKI client capabilities to the desktop operating system, allowing applications to take advantage of desktop cryptographic functionality built in by Microsoft. CAPI has two layers. An interface layer is exposed to the client applications. Underneath is a layer of drivers that perform the cryptographic functions such as encrypting and hashing. The drivers are called Cryptographic Service Providers (see Cryptographic Service Provider (CSP) ). An interface between Microsoft CryptoAPI and private key stores (see key store ), that performs all cryptographic operations for Microsoft applications and any third-party applications that are properly built on the Windows security framework, such as encrypting and decrypting data, verifying signatures, signing data, and verifying certificates. See Cryptographic Service Provider (CSP). A Cryptographic Service Provider (CSP) type. A group of organized CSPs with each group having its own set of data formats. A database (for example, an Informix database) that stores information about users and the Certification Authority (CA). The data is encrypted and protected by passwords. 120 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

121 Term deactivate deactivated user DEBUG decrypt decryption private key DES desktop user digital ID digital signature directory Distinguished Name (DN) DN domain Definition The process of rendering a user incapable of using Entrust. This state is reversible, you can reactivate users later if their certificates have not been revoked (see revoking certificates ). A user whose information is temporarily removed from the corresponding directory entry. The database, however, retains a copy of this information so a deactivated user can be easily reactivated later. For example, you deactivate users when they take a leave of absence. A deactivated user cannot log in to any Entrust application. Deactivating a user increases the number of available licenses by one. An Entrust error level that logs messages relating to the system and used only when debugging the software. The act of restoring an encrypted file to its original, unprotected state. The key that decrypts data that has been encrypted with its corresponding encryption public key. For example, Bob is the only user who has access to his decryption private key, which he uses to decrypt information that has been encrypted for him by other users with his encryption public key. Data Encryption Standard. A NIST-standard algorithm that uses a 56 bit key. Refer to FIPS PUB 46-2 ( The user whose Entrust digital ID is stored in an Entrust desktop security store, located in an.epf file. The set of cryptographic data that defines an entity, consisting of a public portion (user s public certificates) and a private portion (user s private keys), and can be used to verify one s identity. A guarantee to a recipient that the signed file came from the person who sent it, and that it was not altered since it was signed. Any other user who has the corresponding verification public key can verify the signature. A digital signature is the result of making a hash of the data and encrypting the hash using a user s signing private key. An LDAP-compliant directory service that contains the name of all users (see and that acts as repository for user encryption public key certificates. The complete name of a Directory entry that uniquely identifies a person or entity. DNs of all users are stored in the directory. See Distinguished Name (DN). 1) CA domain. 2) The address or registration category of a Web site. Glossary of terms 121

122 Term encrypt encryption key pair encryption public key end user enrollment Entrust certificate file Entrust desktop security store Entrust digital ID Entrust profile Entrust roaming security store Entrust security store entrust.ini file.epf file ERROR Definition The act of rendering a file completely unreadable. This means no one, including the owner of the file, can read the file s contents until it is decrypted. Only the owner and the authorized recipients can decrypt the file. The owner determines authorized recipients. The key pair that contains an encryption public key and associated decryption private key. The key that encrypts data that can be decrypted with the corresponding decryption private key. See encrypt. A user who has successfully enrolled for an Entrust digital ID using an application such as Security Provider for Windows. The process by which an enterprise delivers managed Entrust keys and certificates to an end user or computer, in the form of an Entrust digital ID. The file that contains the necessary information to ensure that files encrypted and signed by someone using an Entrust desktop application in one CA domain can be encrypted and verified by someone using an Entrust desktop application in a non-cross-certified CA domain. All users export their own certificate file and import any user s certificate file. The filename comprises a user name with a.key extension (for example, Alice Gray.key). See.epf file. A digital ID that is created, protected, and managed by Entrust and stored in an Entrust security store and/or a third-party security store. See Entrust digital ID. A password protected Entrust security store file that is located in a directory and accessed only when user s computer is connected to Roaming Server. A password protected file that acts as a storage medium for a user s Entrust digital ID when created with an Entrust Cryptographic Service Provider (CSP). The file that contains important system configuration data that Entrust clients need in order to run. Entrust distributes this file to administrators. A password protected Entrust security store file that is located on user s desktop computer. Also known as Entrust desktop security store. An Entrust error level that logs messages about non-fatal errors, that should, nevertheless, be resolved. For example, application errors. 122 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

123 Term FATAL Globally Unique Identifier (GUID) GUID hardware token Hardware Security Module (HSM) HTTP HTTPS IIS INFO Internet Information Server (IIS) Java Virtual Machine (JVM) JVM key key backup key history key lifetime Definition An Entrust error level that logs messages about fatal errors, that must be resolved. A method for computing object identifiers (OIDs) from Microsoft. See Globally Unique Identifier (GUID). See Hardware Security Module (HSM). A hardware device used to generate key pairs (see key pair ), store the private key, and generate digital signatures (see digital signature ). For information about security hardware support and Entrust products, refer to the for a complete list of Entrust supported hardware tokens, smart cards, biometrics, and other security devices. HyperText Transfer Protocol. A transport protocol to access an unsecured Web server. HyperText Transfer Protocol Secure. A transport protocol used to access a secure Web server through a secure port number. See Secure Sockets Layer (SSL). See Internet Information Server (IIS). An Entrust error level that logs informational messages. A Microsoft Web server application. The part of the Web browser that executes Java applets. See Java Virtual Machine (JVM). A special number that an encryption algorithm uses to change data, making that data secure. The process of maintain a user s decryption keys (see decryption private key ). A collection of decryption private keys belonging to a user, stored by Entrust Managed Services PKI The length of time a key is valid. All keys have a specific lifetime except the decryption private key which never expires. Glossary of terms 123

124 Term key management key pair key recovery key store key update LDAP LDAPS machine Microsoft certificate store Definition Operations that involve: updating all user key pairs (see key pair ) automatically and regularly storing the complete history of each user s encryption key pairs and public key certificates in the database. automatically finding and retrieving a recipient s encryption public key certificates (see encryption public key ) when users want to encrypt for other users automatically including the verification public key certificate of the user who signed the file with the signed file automatically storing the serial number of revoked certificates (see certificate ) in a Certificate Revocation List (CRL) storing the complete history of a user s decryption private keys in their Entrust digital ID so that users can continue to access any information that was encrypted for them. Asymmetric keys come in pairs. Entrust Managed Services PKI uses asymmetric keys in both encryption and digital signature operations. The process of generating new activation codes for a user who has lost their security store or forgotten their password. A store that holds private keys (see private key ) for users and machines and makes them accessible to the Cryptographic Service Provider (CSP) that manages it. The process that replaces old key pair with new ones. During key update, new public key certificates (see certificate ) that have no relation to the old keys and certificates are created and users receive new keys and certificates securely. Lightweight Directory Access Protocol. A Directory Access Protocol (DAP) specified by Internet Engineering Task Force (IETF) RFC Lightweight Directory Access Protocol Secure. A Directory Access Protocol used to access a secure LDAP-compliant Directory through a secure port number. See Secure Sockets Layer (SSL). See computer. A certificate store from Microsoft that contains certificates, CRLs (see Certificate Revocation List (CRL) ), and Certificate Trust List (CTL) that are used by CryptoAPI -enabled devices such as VPN, Internet Authentication Service (IAS), domain controllers, and so on. 124 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

125 Term non-repudiation non-repudiation signing key pair non-repudiation signing private key non-repudiation verification public key organization PKI PKIX PKIX-CMP protocol policy certificate port 80 port 389 port 443 port 636 private key public key Public Key Cryptographic Standards (PKCS) Definition Irrefutable evidence that makes it impossible to reject the validity of one s signature on a file or transaction. An Entrust digital signature provides non-repudiation. It also provides authentication and data integrity. A key pair used for users in high-assurance positions who require separate digital signature and non-repudiation keys. It contains a non-repudiation signing private key and a non-repudiation verification public key. A private key that encrypts a hash value that is decrypted with the corresponding non-repudiation verification public key. The public key portion of a non-repudiation signing key pair used to verify data that has been signed by the corresponding non-repudiation signing private key. A group of people (a company, work group or team, educational or governmental institution) who all use Entrust software under the same software license. See Public Key Infrastructure (PKI). See Public Key Infrastructure X.509 (PKIX). Public Key Infrastructure X.509 (PKIX) - Certificate Management Protocol. The secure communications protocol used to handle requests between Security Provider for Windows and the CA. A certificate that defines privileges for users according to user roles; used to set user policies. The default Web server HTTP port. The default Directory LDAP port. The default Web server HTTPS port. The default Directory LDAPS port. The portion of a key pair that is kept secret by its owner. The portion of a key pair that is available in the directory. A set of standard protocols that facilitate the exchange of information, in a secure manner, over the Internet. Refer to Glossary of terms 125

126 Term Public Key Cryptography Public Key Infrastructure (PKI) Public Key Infrastructure X.509 (PKIX) queuing recovery reference number retrieving users revoking certificates role root CA root certificate store secure operation Definition A cryptographic method that uses keys that are public, for encryption and verification (see encrypt and verify ), and private, for decryption and digitally signing data. 1) A system that provides the basis for establishing and maintaining a trustworthy networking environment through the generation and distribution of keys and certificates. See certificate and key. 2) The foundation technology for providing enhanced Internet security. A working group within the Internet Engineering Task Force (IETF) that has developed standards for formatting and transporting information within a Public Key Infrastructure (PKI). The process of lining up auto-enrollment or auto-recovery requests for approval by an administrator. The operation performed on users who have lost or corrupted their security store. It generates a new signing key pair and retrieves the current encryption public key certificate, decryption private key history, verification public key certificate, and CA verification public key certificate. A number obtained from an administrator, which is used along with an authorization code to create a new certificate. A reference number can only be used once. The process of restoring a user s key history to the database after the user has been archived. The process of stopping a user from using Entrust. You must revoke a user s encryption and verification certificates when the user is no longer trusted (for example, if you suspect that their Entrust digital ID and password have been compromised by an attacker). You can also revoke certificates even when there is no suspicion of compromise (for instance, when a user s DN changes). Your organization can use roles to allows some people to have administrative privileges while restricting other users to an end-user role. The Certification Authority (CA) which is at the top of a hierarchy of two or more CAs, which acts as a trust anchor for all CAs in the hierarchy. The storage medium for the CA certificate when Microsoft Active Directory is not being used. See sensitive operation. 126 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

127 Term Secure Sockets Layer (SSL) user Security Provider for Windows security store sensitive operation serial number server authentication Server Login sign signing key pair Definition A security protocol that provides communications privacy over the Internet. The protocol uses a private key to encrypt data transferred between client/server applications. The protocol allows these applications to communicate in a way that is designed to prevent eavesdropping, tampering, or message forgery. The protocol also allows Web sites and users to authenticate one another s certificates (see certificate ). Both Netscape and Microsoft browsers support SSL, and many Web sites use the protocol to obtain confidential user information, such as credit card numbers. Typically, Web pages that require SSL use the HTTPS protocol. Anyone who uses Security Provider for Windows. An Entrust product that delivers enhanced security management and strong key protection to Microsoft Windows desktop platforms. It is a security management client for Entrust Managed Services PKI. The storage medium for a user s Entrust digital ID. 1) An administrative operation that requires authentication. 2) Any procedure that requires the use of an end user s (see end user ) digital ID. For example, signing or encrypting data. Also known as secure transaction. 3) Any procedure that transmits sensitive information from the end user to an organization without this information becoming compromised. A unique identifier, such as an employee number, that distinguishes a user in the directory from another user with the same name. The authentication whereby the Web server proves its identity to the user by enabling a Secure Sockets Layer (SSL) connection using a Web server certificate. An Entrust product designed for computers, usually servers, that run Entrust applications as services or as background applications. These computers, running 24 hours a day, seven days a week, do not have a user continuously present and are often in a physically secure area that has restricted access. See also credentials file. The act of hashing the data to a fixed-size value using a signing private key to create a digital signature that provides non-repudiation. The key pair that contains a signing private key and a verification public key. Glossary of terms 127

128 Term signing private key Simple Object Access Protocol (SOAP) smart card SOAP SOAP firewall SSL subjectaltname symmetric key tier third-party security store Definition The key that encrypts a hash value that is decrypted with the corresponding verification public key. For example, Alice is the only user who has access to her signing private key, which she uses to encrypt the hash value of a file she is signing, and users verify the signature by successfully decrypting the hash value using Alice s verification public key. Simple Object Access Protocol. A light-weight XML protocol that governs the exchange of information in a distributed environment. SOAP provides a way for programs running in two different operating systems (such as Windows 2000 and Solaris) or written in different programming languages (such as Java and C#) to exchange information, using HTTP and XML. Refer to An electronic memory card about the size of a credit card used primarily for storing data. Smart cards can contain an integrated circuit that can make decisions. Smart cards can be used to retrieve and store certificates (see certificate ). See Simple Object Access Protocol (SOAP). An application-level firewall that watches for Simple Object Access Protocol (SOAP) messages and transforms these messages as they pass through the firewall. See Secure Sockets Layer (SSL). The subjectaltname property provides alternate ways of identifying a user. A single key that both encrypts and decrypts the same data. A high-level division of a system (or application), which groups the components of the system according to their function. A storage medium for user s Entrust digital ID that is commonly password protected, owned by a third-party vendor, and managed by Entrust. 128 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

129 Term third-party trust TRACE Triple-DES trust trusted CA store.ual file URL URS profile User username validity period Definition A situation in which two people implicitly trust each other, even though they have not previously established a personal relationship. In this situation, two people can trust each other if they both have a relationship with a common third party, because the third party can vouch for the trustworthiness of the two people. The need for third-party trust is fundamental to any large-scale implementation of a network security product. Public Key Cryptography requires access to public keys (see public key ). However, in a large-scale network, it is impractical and unrealistic to expect each user to have previously established relationships with all other users. Plus, because public keys must be widely available, the link between a public key and a person must be guaranteed by a trusted third party to prevent masquerading. In effect, users implicitly trust any public key certified by the third party because their organization owns and securely operates the third-party certification agent. An Entrust error level that logs trace messages. A variation of the DES algorithm that uses three 64-bit keys. A relationship between an organization and its end users (see end user ), in which both the organization and the end user can rely on the authenticity of the other to complete sensitive operations, (see sensitive operation ) and/or transmit or view sensitive data, such as a protected resource. A repository of trusted digital IDs (see digital ID ) issued by a non-entrust CA to establish trust so that non-entrust users can access data protected by Entrust software and perform sensitive operations (see sensitive operation ) in a cross-certified environment. The Server Login credentials file, required when you are using Server Login with an Entrust product. Uniform Resource Locator. An Internet address that contains the protocol and domain, and optionally the port and path to a resource. A profile created for the Auto-enrollment Server, and used to: verify signatures, establish SSL connections, sign XAP requests for the XAP Server, sign files that are used by URS. In a Public Key Infrastructure (PKI), an entity that has been identified and approved by a Certification Authority (CA). See end user. A designated term by which a user identifies him or herself to the system. It is not necessarily the equivalent of a user s first name or last name. Also known as the login name, or user ID. See key lifetime. Glossary of terms 129

130 Term verification public key verification public key certificate verify WARNING Web server certificate Web server SSL The public key portion of a signing key pair used to verify data that has been signed by the corresponding signing private key and is stored in the verification public key certificate. The certificate that verifies that the verification public key within it is the authentic public key of the identified user through its digital signature, which is signed by the Certification Authority (CA). The act of providing an auditable record of a transaction, usually in the form of a digital signature, that binds each party to a transaction such they cannot repudiate participating in it. See non-repudiation. An Entrust error level that logs recoverable errors that in normal situations do not occur, such as application warning messages. A certificate issued to a Web server that enables Secure Sockets Layer (SSL) and contains the digital signature of the Certification Authority (CA) that issued it. Secure communication over HTTPS between the Web server and the Web browser Web service A program that runs within an application server that communicates to other requesting components using the Simple Object Access Protocol (SOAP). Web services have two advantages: The SOAP protocol provides a standard way for the Web service and its clients to encode and decode (or "parse") the object code so that programmers don't have to write their own. The standard also means that programs written by different companies can communicate with the Web service. SOAP envelopes are typically sent within HTTP requests so you do not have to open additional ports in your firewall for clients to communicate with the Web service X.509 certificate A standard that ensures interoperability between systems that use digital certificates. See certificate. XAP XML Administration Protocol XML Definition extensible Markup Language. A W3C specification for structured data. Refer to Similar to HTML, XML uses tags and attributes to place structured data into text files. XML is different from HTML in that it is a meta-language and, therefore, does not define specific tags and attributes; it just tells you how to define those tags and attributes. 130 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

131 A Writing your own DN Builder implementation code This appendix provides information to help you write your own DN Builder implementation code. DN Builder examples on page 132 Customizing the DN builder code on page 133 DistinguishedNameBuilderDefaultImp on page 135 ActiveDirectoryUserInfo on page

132 DN Builder examples Auto-enrollment Server installs two DN Builder implementation examples into the following location on your system: <install_directory>\autoenrollmentservices\examples\source\com\ entrust\adminservices\urs\autoenroll where <install_directory> is the installation location of Auto-enrollment Server. By default, the install location is C:\Program Files\Entrust. Read through the following two examples to become familiar with their code: DistinguishedNameBuilderCustomNames.java this sample DN Builder implementation sets a surname, instead of the Windows domain name that is set with the default DistinguishedNameBuilderDefaultImpl. DistinguishedNameBuilderSubjectAltName.java this sample DN Builder implementation sets an address and UPN into the subjectaltname extension in the user s certificate, which the Auto-enrollment Server creates for the client. This implementation cannot be used for computer certificates. 132 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

133 Customizing the DN builder code When you do not want to use the default DistinguishedNameBuilderImpl behavior and Active Directory is not the certificate repository, you can write your own DN builder implementation code. To use your own DN builder code 1 Write your own DN builder logic. Always subclass the default DistinguishedNameBuilderImpl implementation. Refer to the DN Builder examples on page 132 and Customizing the default DN Builder implementation on page Compile your java class. You will need the following two.jar files in your class path: <install directory>\autoenrollmentservices\deploy\adminservicesapp\we B-INF\lib\entrust-urs.jar <install directory>\autoenrollmentservices\deploy\adminservicesapp\we B-INF\lib\entrust-webapp.jar 3 Place the resulting.class file under the classes folder. <install directory>\autoenrollmentservices\deploy\adminservicesapp\we B-INF\classes\ Note: If your class is not in the root package, put it into a folder under the classes folder. 4 Locate the following section of code in the ae-defaults.xml file: <!-- The DistinguishedNameBuilder implementation. Edit this if you provide your own implementation class. --> <DNBuilder>DistinguishedNameBuilderDefaultImpl</DNBuilder> 5 Edit the <DNBuilder> value with the name of the java class you just created. For example, if your new java class name is DNBuilderMyCustomClass.class your ae-defaults.xml file will look like this: <DNBuilder>DNBuilderMyCustomClass</DNBuilder> This example assumes that your class is in the root package. 6 Restart the Auto-enrollment Server service in Windows Services. 7 When you have manually restarted the Auto-enrollment Server service, the adminservices.log file should display the following event: Writing your own DN Builder implementation code 133

134 [ :38: ][TRACE][UserRegistrationService][][][] AE Server - DN builder: DNBuilderMyCustomClass 134 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

135 DistinguishedNameBuilderDefaultImp The public class DistinguishedNameBuilderDefaultImpl implements DistinguishedNameBuilder. The following sections provide you with all of the information needed to customize your own DN Builder implementation: Customizing the default DN Builder implementation on page 135 Constructor Summary on page 136 Method Summary on page 136 Constructor Detail on page 139 Method Detail on page 139 Refer to the section Customizing a user s Distinguished Name (DN) on page 97 for further information on the default DN builder implementation. Customizing the default DN Builder implementation Subclass the default DistinguishedNameBuilderDefaultImpl and override one or more of its methods. The Auto-enrollment Server invokes the methods in this order: First, it sets aside static data; 1 The constructor sets the CA search base. 2 setsearchbases(.) 3 setactivedirectory(.) 4 setusertype(.) On every client request, the Auto-enrollment Server provides the following information to the DN Builder: setdomainandname(.) setmachinecertificate(.) setclientagent(.) setclientdigitalidtype(.) setadditionalinfo(.) setactivedirectoryuserinfo(.) To access this information, your DN Builder implementation can use the accessor methods in the DistinguishedNameBuilderDefaultImpl, its super class. 5 To change the default behavior, you may create a DN, common name, and surname by overriding the following: buildclientdn() Writing your own DN Builder implementation code 135

136 Your implementation should provide a surname, unless you are using Active Directory, because the PKI makes that mandatory for user type Person. 6 Optionally, create different SubjectAltName extensions by overriding the following: buildsubjectaltname(); The server will retrieve the contents of your DN Builder by invoking the following methods: getdistinguishedname() getcommonname() getsurname() getsubjectaltname() Your implementation overrides the above methods, returning the strings that it builds in its buildclientdn() and buildsubjectaltname() implementations, if any. 7 Optionally, your implementation may override the following: getserialnumber() Your subclass might use the following helper method to provide the dns name of the client computer: String getdnsname (String windowsdomain) Constructor Summary Method Summary DistinguishedNameBuilderDefaultImpl () Table 4: Class DistinguishedNameBuilderImpl Method Summary Method Summary void buildclientdn () Implements a procedure for building the distinguished name. void buildsubjectaltname () Implements a procedure for building a SubjectAltName. ActiveDirectoryUserInfo getactivedirectoryuserinfo () Convenience method that accesses any client information that the Auto-enrollment Server may have set into the DistinguishedNameBuilder, when Active Directory is being used. 136 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

137 Table 4: Class DistinguishedNameBuilderImpl Method Summary Method Summary java.lang.string [] getadditionainfo () Gets the AdditonaInfo the client sent in its SOAP request, if any. java.lang.string getclientagent () Gets the client agent the client sent in its SOAP request, if any. int getclientdigitalidtype () Gets the client digital ID the client sent in its SOAP request, if any. java.lang.string getcommonname () Gets the common name this implementation has built. java.lang.string getdistinguishedname () Gets the distinguished name this implementation has built. java.lang.string getdnsname (DomainAndName domainandname) Helper method that returns the DNS name of the client computer. DomainAndName getdomainandname () Gets the Windows domain and name of the client. java.lang.string getnameca () Get the CA name this implementation can use when building a DN. SearchBases getsearchbases () Gets the search bases this implementation can use when building a DN. java.lang.string getserialnumber () Gets the serial number. java.lang.string [] getsubjectaltname () Gets any SubjectAltName strings that were built by the DN builder implementation. java.lang.string getsurname () Gets the surname this implementation has built. java.lang.string getusertype () Returns the default user type in effect. Writing your own DN Builder implementation code 137

138 Table 4: Class DistinguishedNameBuilderImpl Method Summary Method Summary boolean isactivedirectory () Returns true if the ae-defaults.xml configuration says that Active Directory is being used as the certificate repository. boolean ismachinecertificate () Returns true if theclient has requested enrollment of a computer, not a user. void setactivedirectory (boolean activedirectory) Invoked by the server when activedirectory is set to true, if the ae-defaults.xml configuration says that Active Directory is being used as the certificate repository. void setactivedirectoryuserinfo (ActiveDirectoryUserInfo userinfo) Invoked by the server when the Auto-enrollment Server configuration indicates that Active Directory is being used. void setadditionainfo (java.lang.string [] additionainfo) Save additional information the client might have sent in its request, if any. void setclientagent (java.lang.string clientagent) Sets whatever client agent string the client might have sent in its request, if any. void setclientdigitalidtype (int clienttype) Sets the type of client digital ID that the client reported in its SOAP request message, if any. void setcommonname (java.lang.string cn) Sets the common name this implementation will use. void setdomainandname (DomainAndName domainandname) Sets the Windows domain and name of the client void setmachinecertificate (boolean ismachine) Invoked by the server with ismachine set to true, if the client has requested enrollment of a computer, not a user. void setnameca (java.lang.string dn) Sets the name of the CA. 138 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

139 Table 4: Class DistinguishedNameBuilderImpl Method Summary Method Summary void void void void setsearchbases (SearchBases searchbases) Sets the search bases to use when building the DN. setsubjectaltname (java.lang.string [] subjectaltname) Sets the SubjectAltName this implementation will use. setsurname (java.lang.string surname) Sets the surname this implementation will use. setusertype (java.lang.string usertype) Sets the default user type. Constructor Detail Method Detail DistinguishedNameBuilderDefaultImpl public DistinguishedNameBuilderDefaultImpl () setmachinecertificate public void setmachinecertificate (boolean ismachine) Invoked by the server with ismachine set to true, if the client has requested enrollment of a computer not a user. The DistinguishedNameBuilder implementation might use this information or ignore it, when it builds a SubjectAltName or a DN. Specified by: setmachinecertificate in interface DistinguishedNameBuilder Parameters: ismachine set to true if the enrollment is for machine certificate, not a user certificate. setactivedirectory public void setactivedirectory (boolean activedirectory) Invoked by the server with activedirectory set to true, if the ae-defaults.xml configuration says that Active Directory is being used as the certificate repository. Writing your own DN Builder implementation code 139

140 A customized DistinguishedNameBuilder implementation might use this information when it builds a SubjectAltName or a DN. Specified by: setactivedirectory in interface DistinguishedNameBuilder Parameters: activedirectory is strue if using Active Directory as the certificate repository. isactivedirectory public boolean isactivedirectory () Returns true if the ae-defaults.xml configuration says that Active Directory is being used as the certificate repository. A customized DistinguishedNameBuilder implementation might use this information when it builds a SubjectAltName or a DN. Specified by: isactivedirectory in interface DistinguishedNameBuilder Returns: true if using an Active Directory certificate repository. setdomainandname public void setdomainandname (DomainAndName domainandname) throws DistinguishedNameBuilderException Sets the Windows domain and name of the client. Invoked by the server to provide a DistinguishedNameBuilder implementation with the domain and name of the user making the request. Specified by: setdomainandname in interface DistinguishedNameBuilder Parameters: domainandname the DomainAndName Throws: DistinguishedNameBuilderException getactivedirectoryuserinfo public ActiveDirectoryUserInfo getactivedirectoryuserinfo () Convenience method that accesses any client information the Auto-enrollment Server may have set into this DistinguishedNameBuilder, when ActiveDirectory is 140 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

141 being used. Your customized DistinguishedNameBuilder implementation might use this information to build the DN or SubjectAltName. Refer to the ActiveDirectoryUserInfo on page 149 for its content. Note: This method is provided only for the convenience of the implementations that subclass DistinguishedNameBuilderDefaultImpl. The Auto-enrollment Server doesn t invoke this by default. Specified by: getactivedirectoryuserinfo in interface DistinguishedNameBuilder Returns: the ActiveDirectoryUserInfo or null See also: isactivedirectory buildclientdn public void buildclientdn () throws DistinguishedNameBuilderException Implements a procedure for building the distinguished name. Invoked by the Auto-enrollment server before it invokes getdistinguishedname(), getcommonname(), and getsurname(). Default implementation sets the common name to be the user or machine name and the surname to be the domain. The client is enrolled on the search base set in the Auto-enrollment Server s ae-config.xml, or the CA search base if the configuration did not provide it. If your Auto-enrollment Server is using an Active Directory, this method uses the information provided by the Directory to get the distinguished name of the user. You must configure the ae-defaults.xml settings so the server can access the directory. Specified by: buildclientdn in interface DistinguishedNameBuilder Throws: DistinguishedNameBuilderException buildsubjectaltname public void buildsubjectaltname () throws DistinguishedNameBuilderException Writing your own DN Builder implementation code 141

142 Implements a procedure for building a SubjectAltName. This default implementation sets a DNS name for all computer enrollments. In addition, it sets a GUID as an othername, if the client requested a domain controller certificate. The result is retrieved by getsubjectaltname(). If the Auto-enrollment Server is using an Active Directory, this method reads the Directory to get the address and userprincipalname, if any, so they can be set as SubjectAltName extensions. Specified by: buildsubjectaltname in interface DistinguishedNameBuilder Throws: DistinguishedNameBuilderException getnameca public java.lang.string getnameca () Get the CA name this implementation can use when building a DN. Specified by: getnameca in interface DistinguishedNameBuilder Returns: the distinguished name of the issuer of the verification certificate of Auto-enrollment Server administrator (URS admin) setnameca public void setnameca (java.lang.string dn) Sets the name of the CA. Specified by: setnameca in interface DistinguishedNameBuilder Parameters: dn the name of the CA setsearchbases public void setsearchbases (SearchBases searchbases) Sets the search bases to use when building the DN. Invoked by the Auto-enrollment Server, if the Auto-enrollment Server configuration provides a search base in its configuration parameters. Specified by: setsearchbases in interface DistinguishedNameBuilder 142 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

143 Parameters: searchbases the searchbases for users and computers getsearchbases public SearchBases getsearchbases () Gets the search bases this implementation can use when building a DN. Search bases for user and machine enrollments can be configured in the ae-defaults.xml file. setadditionainfo public void setadditionainfo (java.lang.string [] additionainfo) Save additional information the client might have sent in its request, if any. Invoked by the Auto-enrollment Server, to provide this information to a DistinguishedNameBuilder. Specified by: setadditionainfo in interface DistinguishedNameBuilder Parameters: additionainfo the AdditionaInfo strings which were in the client SOAP request message, if any. getadditionainfo public java.lang.string [] getadditionainfo () Gets the AdditionaInfo the client sent in its SOAP request, if any. setclientagent public void setclientagent (java.lang.string clientagent) Sets whatever client agent string the client might have sent in its request, if any. Invoked by the Auto-enrollment Server, to provide this information to a DistinguishedNameBuilder. Specified by: setclientagent in interface DistinguishedNameBuilder Parameters: clientagent the string received in the client SOAP request message, if any. getclientagent public java.lang.string getclientagent () Writing your own DN Builder implementation code 143

144 Gets the client agent the client sent in its SOAP request, if any. setclientdigitalidtype public void setclientdigitalidtype (int clienttype) throws DistinguishedNameBuilderException Sets the type of client digital ID that the client reported in its SOAP request message, if any. Invoked by the Auto-enrollment Server, to provide this information to a DistinguishedNameBuilder. The allowed values are enumerated in AutoEnrollConstants. Specified by: setclientdigitalidtype in interface DistinguishedNameBuilder Parameters: clienttype the value received in the client SOAP request message, if any. Throws: DistinguishedNameBuilderException getclientdigitalidtype public int getclientdigitalidtype () Gets the client digital ID the client sent in its SOAP request, if any. The allowed values are enumerated in AutoEnrollConstants. getserialnumber public java.lang.string getserialnumber () Gets the serial number. This default implementation returns null. Specified by: getserialnumber in interface DistinguishedNameBuilder Returns: the serial number ismachinecertificate public boolean ismachinecertificate () Returns true if the client has requested enrollment of a computer, not a user. A customized DistinguishedNameBuilder implementation might use this information when it builds a SubjectAltName or a DN. Specified by: 144 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

145 ismachinecertificate in interface DistinguishedNameBuilder getdomainandname public DomainAndName getdomainandname () Gets the Windows domain and name of the client. Specified by: getdomainandname in interface DistinguishedNameBuilder Returns: the DomainAndName that the Auto-enrollment Server set into this instance, or null. getdistinguishedname public java.lang.string getdistinguishedname () Gets the distinguished name this implementation has built. Specified by: getdistinguishedname in interface DistinguishedNameBuilder Returns: the distinguished name getcommonname public java.lang.string getcommonname () Gets the common name this implementation has built. This default implementation sets the common name to be the client s Windows logon name. Specified by: getcommonname in interface DistinguishedNameBuilder Returns: the common name setcommonname public void setcommonname (java.lang.string cn) Sets the common name this implementation will use. The Auto-enrollment Server does not invoke this method, but your customized subclass might invoke it. Otherwise, this default implementation sets the common to be the client s Windows user name. Specified by: Writing your own DN Builder implementation code 145

146 setcommonname in interface DistinguishedNameBuilder Parameters: cn the common name getsurname public java.lang.string getsurname () Gets the surname this implementation has built. This default implementation sets the surname to be the client s Windows domain. Note: Unless you are using Active Directory, your implementation should provide a surname, because it is mandatory for the user type Person. Specified by: getsurname in interface DistinguishedNameBuilder Returns: the surname setsurname public void setsurname (java.lang.string surname) Sets the surname this implementation will use. The Auto-enrollment Server does not invoke this method itself, but your customized subclass might invoke it. Otherwise, this default implementation sets the surname to be the client s WIndows domain. Specified by: setsurname in interface DistinguishedNameBuilder Parameters: surname the surname getsubjectaltname public java.lang.string [] getsubjectaltname () Get any SubjectAltName strings that were built by the DN builder implementation. Specified by: getsubjectaltname in interface DistinguishedNameBuilder Returns: subjectaltname the SubjectAltName 146 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

147 getusertype public java.lang.string getusertype () Returns the default user type in effect. For example: Person Domain User A customized DistinguishedNameBuilder implementation may use this information to build a DN. For example, a Person must be given a surname, while a Domain User must not. Specified by: getusertype in interface DistinguishedNameBuilder Returns: the default user type setactivedirectoryuserinfo public void setactivedirectoryuserinfo (ActiveDirectoryUserInfo userinfo) Invoked by the Auto-enrollment Server when the ae-config.xml indicates that Active Directory is being used. A customized DistinguishedNameBuilder implementation might use this information when it sets a SubjectAltName or a DN. This default implementation gets the DN, address, and UPN from this ActiveDirectoryUserInfo. Specified by: setactivedirectoryuserinfo in interface DistinguishedNameBuilder Parameters: userinfo has the ActiveDirectoryUserInfo that the server reads from the Active Directory getdnsname public java.lang.string getdnsname (DomainAndName domainandname) throws DistinguishedNameBuilderException Helper method that returns the DNS name of a client computer. The enrollment request must have come from a computer, not a user. First, this method performs a DNS look up, to get the client host name given its IP address. If that fails, it refers to the mapping that you configure in the ae-defaults.xml file. For example, you may map ACME_HQ to acme.com, so a machine named webserver would get the DNS name webserver.acme.com from this method. Writing your own DN Builder implementation code 147

148 If there is no mapping in ae-defaults.xml, this method throws an exception. Specified by: getdnsname in interface DistinguishedNameBuilder Returns: the DNS name Throws: DistinguishedNameBuilderException if a DNS name cannot be returned 148 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

149 ActiveDirectoryUserInfo The public final class ActiveDirectoryUserInfo contains client information that Auto-enrollment Server may read from a Microsoft Active Directory. The following sections provide you with information needed to understand what client information may be read from an Active Directory. Method Summary on page 149 Method Detail on page 149 Method Summary Table 5: Class ActiveDirectoryUserInfo Method Summary Method summary java.lang.string getcommonname () Returns the common name. java.lang.string getdistinguishedname () Returns the distinguished name. java.lang.string get () Returns . java.lang.string getfirstname () Returns the first name. java.lang.string getsurname () Returns the surname. java.lang.string getupn () Returns the upn. java.lang.string getwindowsaccountname () Returns the Windows logon name. Method Detail getcommonname public java.lang.string getcommonname () Returns the common name. Writing your own DN Builder implementation code 149

150 Returns: String getdistinguishedname public java.lang.string getdistinguishedname () Returns the distinguished name. Returns: String get public java.lang.string get () Returns the . Returns: String getfirstname public java.lang.string getfirstname () Returns the first name. Returns: String getsurname public java.lang.string getsurname () Returns the surname. Returns: String getupn public java.lang.string getupn () Returns the upn. Returns: String 150 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

151 getwindowsaccountname public java.lang.string getwindowsaccountname () Returns the Windows logon name. Returns: String Writing your own DN Builder implementation code 151

152 152 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 1.0

153 Index - A B C D E F G H I J K L M N O P Q R S T U V W X Y Z-.epf file definition 122.ual file definition 129 A About Auto-enrollment Server 7 activation codes definition 117 active user definition 117 ActiveDirectoryUserInfo class 149 added user definition 117 administrator definition 117 ae-config.xml 89 ae-defaults.xml 89 ALERT definition 117 algorithm DES definition 121 Triple-DES definition 129 attribute definition 117 authentication definition 118 authorization code definition 118 authorize definition 118 C CA certificate definition 118 root definition 126 signing key pair definition 118 signing private key definition 118 verification public key definition 118 CA issuer definition 118 cache definition 118 CAPI definition 118 certificate certificate category definition 119 certificate type definition 119 definition 119 validation definition 119 Web server certificate definition 130 X.509 certificate definition 130 certificate expiry definition 119 certificate revocation see certificate 119 Certificate Revocation List (CRL) definition 119 certificate store definition 119 Microsoft definition 124 root definition 126 certificate type and role 13 certificates revocation definition 126 Certification Authority (CA) 153

154 - A B C D E F G H I J K L M N O P Q R S T U V W X Y Z- definition 119 client definition 119 client authentication definition 120 client information setting 93 computer definition 120 credentials credentials file definition 120 definition 120 CRL check definition 120 CryptoAPI definition 120 Cryptographic Service Provider (CSP) definition 120 CSP type definition 120 D Database 12 database definition 120 deactivate definition 121 DEBUG definition 121 decrypt definition 121 decryption private key definition 121 desktop user definition 121 digital ID definition 121 digital signature definition 121 Directory 12 directory definition 121 Distinguished Name (DN) customizing 97 definition 121 DistinguishedNameBuilderDefaultImpl class 135 DistinguishedNameBuilderImpl 97 DN builder implementation 16 DNBuilderSearchBase 98 dns name configuring 99 domain see CA domain 121 E encrypt definition 122 encryption key pair definition 122 encryption public key definition 122 end user definition 122 enrollment definition 122 Entrust Authority Security Manager 11 Entrust certificate file definition 122 Entrust desktop security store definition 122 Entrust digital ID definition 122 Entrust Entelligence Security Provider for Windows 10 Entrust roaming security store definition 122 Entrust security store definition 122 entrust.ini file definition 122 ERROR definition 122 error messages 116 F FATAL definition 123 File Structure 86 G Globally Unique Identifier (GUID) definition Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 4.0

155 - A B C D E F G H I J K L M N O P Q R S T U V W X Y Z- H L Hardware Security Module (HSM) definition 123 HTTP definition 123 HTTPS definition 123 I INFO definition 123 Installation planning 20 Installing Auto-enrollment Server 74 checking 86 Internet Information Server (IIS) definition 123 J Java Virtual Machine (JVM) definition 123 K key definition 123 key backup definition 123 key history definition 123 key lifetime definition 123 key pair definition 124 key recovery definition 124 key store definition 124 key update definition 124 management definition 124 key store definition 124 LDAP definition 124 LDAPS definition 124 logging 110 log file location 111 log level 110 maximum log file size 112 maximum message length 114 number of backup log files allowed 113 M machine definition 124 Microsoft Internet Information Services (IIS) Web Serve 11 N non-repudiation definition 125 signing key pair definition 125 signing private key definition 125 verification public key definition 125 non-repudiation signing key pair definition 125 non-repudiation signing private key definition 125 non-repudiation verification public key definition 125 O organization definition 125 P PKIX-CMP protocol definition 125 policy certificate definition 125 Index 155

156 - A B C D E F G H I J K L M N O P Q R S T U V W X Y Z- port 389 definition definition definition definition 125 private key decryption definition 121 definition 125 signing definition 128 public key definition 125 Public Key Cryptography definition 126 Public Key Infrastructure (PKI) definition 126 Public Key Infrastructure X.509 (PKIX) definition 126 Q queuing 101 definition 126 enabling in Auto-enrollment Server 102 R recovery definition 126 reference number definition 126 retrieving users definition 126 role definition 126 S search base customizing 98 DNBuilderSearchBase 98 Secure Sockets Layer (SSL) definition 127 Security Provider definition 127 Security Provider for Outlook Overview 8 Security Provider for Windows 10 AutoEnrollMachineDigitalIDType 93 AutoEnrollMachineURL 10 AutoEnrollUserDigitalIDType 93 AutoEnrollUserURL 10 security store definition 127 Entrust security store definition 122 sensitive operation definition 127 serial number definition 127 server authentication definition 127 Server Login definition 127 sign definition 127 signing key pair definition 127 signing private key definition 128 Simple Object Access Protocol (SOAP) definition 128 smart card definition 128 SOAP SOAP firewall definition 128 subjectaltname definition 128 subjectaltname creation 17 domain controller certificates 17 symmetric key definition 128 system components 9 T third-party security store definition 128 third-party trust definition Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 4.0

157 - A B C D E F G H I J K L M N O P Q R S T U V W X Y Z- Three-Tier client/server environment 9 tier definition 128 Tier 1 10 Tier 2 10 Tier 3 11 time synchronization 115 Tomcat Application Server 11 TRACE definition 129 trust definition 129 trusted CA store definition 129 U URL definition 129 URS profile creating 61 definition 129 User definition 129 user deactivated definition 121 definition 127 username definition 129 V validity period see key lifetime 129 verification public key definition 130 verification public key certificate definition 130 verify definition 130 W WARNING definition 130 Web Server creating and installing certificate 24 enabling SSL 51 Web server SSL definition 130 Web service definition 130 X XAP definition 130 XML definition 130 Index 157

158 - A B C D E F G H I J K L M N O P Q R S T U V W X Y Z- 158 Auto-enrollment Server 7.0 Installation and Configuration Guide Document issue: 4.0