Managed PKI. Certificate Validation and Parsing Guide CUSTOMER MANUAL. Customer Support: +44(0)

Transcription

1 Managed PKI Certificate Validation and Parsing Guide CUSTOMER MANUAL Customer Support: +44(0) BT38-MPKI6-CVM-V1.0

2 Managed PKI Certificate Validation and Parsing Guide Managed PKI Certificate Validation and Parsing Guide BT38-MPKI6-CVM-V1.0 has been produced from VeriSign Inc. Doc Ref: Copyright VeriSign, Inc. All rights reserved. Printed in the United States of America. Publication date: August 2003 BT Revision date: October 2005 This document supports Managed PKI 6.0 and all subsequent releases unless otherwise indicated in a new edition or release notes. Trademark Notices VeriSign is a registered trademark of VeriSign, Inc. The VeriSign logo, VeriSign Trust Network, and Go Secure! are trademarks and service marks of VeriSign Inc. XMLPay and OnSite are registered trademarks of VeriSign, Inc. Other trademarks and service marks in this document are the property of their respective owners. No part of this publication may be reproduced, stored in or introduced into a retrieval system, or transmitted, in any form or by any means (electronic, mechanical, photographic, audio, or otherwise) without prior written permission of VeriSign, Inc. Notwithstanding the above, permission is granted to reproduce and distribute this document on a nonexclusive, royalty-free basis, provided that (i) the foregoing copyright notice and the beginning paragraphs are prominently displayed at the beginning of each copy, and (ii) this document is accurately reproduced in full, complete form with attribution of the document to VeriSign, Inc BT Notice This software and the corresponding documentation are being provided to you in conjunction with the products and services provided to you by BT. The software and documentation was originally designed to be used with products and services offered directly by VeriSign to its customers. BT is offering substantially the same products and services to you as VeriSign provides to its customers. The software and documentation, however, may have been translated and localized by BT. BT assumes all responsibility for the translation and localization of the software and documentation, and VeriSign disclaims any and all warranties, express, implied, or statutory, including without limitation any implied warranty of merchantability or fitness for a particular purpose and refuses liability for such translation and localization. Note This document may describe features and/or functionality that are not present in your software or your service agreement. Contact your account representative to learn more about what is available with this VeriSign product. ii BT38-MPKI6-CVM-V1.0

3 Contents Contents Chapter 1 Introduction About this Guide Chapter 2 Certificate Validation Module (CVM) Components of CVM Functions of CVM CRL Status Checking OCSP Status Checking Chapter 3 Installing and Configuring the CVM Filter for Microsoft IIS Obtaining the CVM files Installing and Configuring the CVM for Your Web Server Optional: Configuring OCSP and Additional Installation Requirements CVM and OCSP Service Configuring CVM to Fit Other Installation Requirements Chapter 4 Installing and Configuring the CVM Filter for Microsoft ISA Server Obtaining the CVM files Installing and Configuring the CVM for Your Web Server Configuring OCSP and Additional Installation Requirements (Optional).. 32 CVM and OCSP Service Configuring the CVM to Fit Other Installation Requirements Chapter 5 Installing and Configuring the CVM Plug-In for SunONE Enterprise Server Obtaining the CVM files Installing and Configuring the CVM for Your Web Server Optional: Configuring OCSP and Additional Installation Requirements CVM and OCSP Service Configuring the CVM to Fit Other Installation Requirements BT38-MPKI6-CVM-V1.0 iii

4 Managed PKI Certificate Validation and Parsing Guide Chapter 6 Installing and Configuring the CVM Module for Stronghold Secure Web Server Obtaining the CVM files Installing and Configuring the CVM for Your Web Server Optional: Configuring OCSP and Additional Installation Requirements CVM and OCSP Service Configuring CVM to Fit Other Installation Requirements Chapter 7 VeriSign Certificate Parsing Module (CPM) Components of the CPM Software Suite Fields Extracted by CPM Programmer s Library File CPM Implementations Option 1: Configuring the Server Plug-in Version of CPM Option 2: Configuring the CPM Programmer s Library Using the Server Plug-In Using the Programmer s Library Certificate Parsing API Supported Platforms Operation CPM API Function Descriptions Chapter 8 Online Certificate Status Protocol (OCSP) Background Contrasting OCSP and CRL Services How OCSP Services Works with CVM Enabling the CVM for OCSP Service Appendix A CVM Configuration Values iv BT38-MPKI6-CVM-V1.0

5 Contents Appendix B Downloading Certificate Revocation Lists Managed PKI Public Production System Pilot System MPKI Private Production System Pilot System MPKI Testdrive Index BT38-MPKI6-CVM-V1.0 v

6 Managed PKI Certificate Validation and Parsing Guide vi BT38-MPKI6-CVM-V1.0

7 re t pahc CHAPTER 1 1Introduction In its role as a Certification Authority, BT provides certificate revocation information in two forms: Certificate Revocation Lists (CRLs) and Online Certificate Status Protocol (OCSP) services. Before trusting a certificate, end-user software must determine whether the certificate is valid by checking the corresponding CRL or OCSP service. During a transaction, the Certificate Validation Module (CVM) automatically and transparently verifies a certificate s status (valid, expired, revoked, suspended, or unknown) before allowing access to a protected Web site or resource. CVM verifies a certificate s status by either downloading and installing the most recent CRL published by BT Trust Services (usually, a new CRL is generated every 24 hours) into the Web server, or by sending an OCSP request for real-time certificate status to the CA s OCSP responder. BT and VeriSign regularly update, and make available to the public, CRLs and OCSP services for each Certification Authority (CA). Premium Revocation Service is available in two forms: CRLs generated every hour and OCSP service. Certificate Revocation List (CRL). A CRL is a dated and signed list of revoked certificates. When a certificate is presented to a Web server or other network resource, an application checks the certificate against the CRL. If the certificate is listed as revoked or not valid, the user presenting the certificate cannot access the resource. If the certificate is not listed, the user presenting the certificate is allowed access to the resource. Online Certificate Status Protocol (OCSP). OCSP is an add-on service that provides automated responses to requests for certificate revocation status (valid, revoked, suspended, expired, or unknown) in real-time. When a certificate is presented to a Web server or other network resource, CVM sends BT38-MPKI6-CVM-V1.0 1

8 Managed PKI Certificate Validation and Parsing Guide an OCSP request for certificate status to the CA s OCSP responder. If the OCSP response is valid, the user presenting the certificate can access the resource. If the response is revoked, suspended, expired or unknown, the user presenting the certificate cannot access the resource. VeriSign s Certificate Parsing Module (CPM) is a software suite that extracts fields from certificates presented to a Web server and makes that information available to certificate-enabled applications. The software suite is available as a Web server plug-in for Netscape Server API (NSAPI or SAF), or as a programmers library (*.so or *.dll) file for use with C, C++, and other programming languages. CVM and CPM are the two certificate management tools provided with VeriSign Managed PKI. These modules typically are used in conjunction with a Web server that is using native client authentication, and may be installed with Go Secure! for Web Applications. These tools can also be used independently of Go Secure! for Web Applications, or of each other. About this Guide This guide contains technical material to help system administrators install and configure the CVM and CPM certificate management tools. The guide also discusses the OCSP service and how it works with CVM to determine the status of a particular certificate in real time. Note In this guide, the term Netscape/iPlanet is defined as Netscape Enterprise Server 3.x, iplanet Enterprise Server 4.x or 6.x, or Sun ONE Web Server 6.x on any of the supported platforms. This document is organized as follows: Chapter 2, Certificate Validation Module (CVM), describes CVM s components and functions, as well as the hardware and software requirements for using CVM. Chapter 3, Installing and Configuring the CVM Filter for Microsoft IIS, provides the procedures for obtaining, installing, and configuring the CVM for Microsoft Internet Information Server. 2 BT38-MPKI6-CVM-V1.0

9 Chapter 1 Introduction Chapter 4, Installing and Configuring the CVM Filter for Microsoft ISA Server, provides the procedures for obtaining, installing and configuring the CVM for Microsoft ISA server. Chapter 5, Installing and Configuring the CVM Plug-In for SunONE Enterprise Server, provides the procedures for obtaining, installing, and configuring the CVM for SunONE Enterprise Server. Chapter 6, Installing and Configuring the CVM Module for Stronghold Secure Web Server, provides the procedures for obtaining, installing, and configuring the CVM for Stronghold. Chapter 7, VeriSign Certificate Parsing Module (CPM), describes CPM s components and functions, as well as the hardware and software requirements for using CPM. This chapter also provides installation and configuration procedures for CPM. Chapter 8, Online Certificate Status Protocol (OCSP), describes BT s Online Certificate Status Protocol service, which enables OCSP users and applications to determine the status of a certificate in real time. Appendix A, CVM Configuration Values, contains the values for configuring the CVM with obj.conf, httpd.conf, or valconfig.exe. Appendix B, Downloading Certificate Revocation Lists, lists the secure Web page URLs for downloading CRLs for Managed PKI Public and Private hierarchies. BT38-MPKI6-CVM-V1.0 3

10 Managed PKI Certificate Validation and Parsing Guide 4 BT38-MPKI6-CVM-V1.0

11 re t pahc CHAPTER 2 2Certificate Validation Module (CVM) VeriSign s Certificate Validation Module (CVM) software suite provides ready-to-use Web server plug-ins that simplify certificate status-checking. CVM automatically and transparently verifies a certificate s status (valid, expired, revoked, suspended, or unknown) before allowing access to a protected Web resource. CVM verifies a certificate s status by either downloading and installing the most recent CRLs published by BT or VeriSign into the Web server, or by sending an OCSP request for real-time certificate status to the CA s OCSP responder. CVM includes plug-ins for Netscape/iPlanet Enterprise Server, Microsoft Internet Information Server (IIS), and Stronghold Secure Web Server. These products (for both Public and Private Managed PKI services) are discussed in this chapter. Components of CVM The following files are included with the Certificate Validation Module (Windows2000/Windows 2003 versions use *.dll files, the HP-UX version uses *.sl files, and the Solaris version uses *.so files.) File nsldapssl32v30.(*.dll, *.sl, *.so) libvsvalsdk.(*.dll, *.sl, *.so) val_config.txt certstatus.csh certstatus.pl Description LDAP library Validation library Sample trust configuration file Sample customized certificate error CGI (C shell) Sample customized certificate error CGI (Perl) BT38-MPKI6-CVM-V1.0 5

12 Managed PKI Certificate Validation and Parsing Guide File (Continued) libvsvaln.(dll, sl, so) libvsvalm.dll mod_vsval.(sl, so) valconfig.exe onsite_sub_demo.509 g2_class2testroot.509 g2_verisign_class2_onsite_individual_test_ca. 509 g2_pca2ss.509 g2_vs_class2_onsite_individual_ca_2.509g2_ Description (Continued) Server plug-in (Netscape Only) Server filter (Microsoft Only) Server module for Stronghold Configuration program (Microsoft Only) TestDrive CA Pilot Managed PKI Root CA Pilot Managed PKI Public Signer (Intermediate) CA Managed PKI Root CA Managed PKI Public Signer (Intermediate) CA Functions of CVM The CVM checks the validity of all client-authentication certificates presented to the Web server using either CRL status checking or OCSP status checking. The CVM can be configured for one method only. CRL Status Checking The CVM can read and acquire CRLs from any combination of local files, HTTP servers, or LDAP servers. It caches the CRLs into a local directory on the Web server and refreshes them when necessary. Before trusting received data, the CVM always verifies the data s digital signature. The CVM is fully configured through a text file, and can be operated in manual or automatic mode. When the Web server starts, the CVM first acquires any required CRLs and stores them in a local cache directory. If a recent copy is already present in the cache, the CVM uses that version. The CVM then reads all of the CRLs and certificates into its internal database. The Web server is then ready to begin servicing client requests. During a Secure Sockets Layer (SSL) session, the Web server requests a certificate from the client. The CVM verifies that the certificate has not been revoked, and 6 BT38-MPKI6-CVM-V1.0

13 Chapter 2 Certificate Validation Module (CVM) ends the transaction if the certificate is not valid. If the CVM determines that its CRL information has become out of date, it automatically attempts to re-acquire the CRLs. The CVM can optionally log information about its operation, including logging requests that were denied for security reasons. OCSP Status Checking During an SSL session, the Web server requests a certificate from the client. The CVM obtains this certificate from the Web server and parses identifying information from it. The CVM forwards that information to an OCSP responder server across an Internet connection in the form of an OCSP request. The OCSP responder verifies the certificate s status (valid, revoked, suspended, expired or unknown), creates and digitally signs an OCSP response, and returns the response to the CVM. Based on the response content and signature returned by the OCSP responder, the CVM grants or denies access to the Web resource: If the OCSP response states the certificate is valid, the user is taken directly to the resource. If the OCSP response states that the certificate is revoked or suspended, CVM displays the default message of Certificate Revoked, and the user is denied access to the resource. If the OCSP response states the certificate is expired, CVM displays the default message Certificate Expired, and the user is denied access to the resource. If the OCSP responder certificate has expired, CVM displays the same error message and writes this to the log file. If the OCSP response is unknown, CVM displays the default message Server Error: Revocation Unknown, and the user is denied access to the resource. If the OCSP response returns any other non-valid status, CVM displays the default message Server Error: Certificate Failed, and the user is denied access to the resource. CVM writes additional information about this error to the log file. These messages are fully customizable with the existing error-cgi option in the obj.conf (Netscape/iPlanet Enterprise Server), valconfig.exe (Microsoft Internet Information Server), or httpd.conf (Stronghold Secure Web Server). BT38-MPKI6-CVM-V1.0 7

14 Managed PKI Certificate Validation and Parsing Guide 8 BT38-MPKI6-CVM-V1.0

15 re t pahc CHAPTER 3 3Installing and Configuring the CVM Filter for Microsoft IIS This chapter describes the procedures for obtaining, installing and configuring the CVM filter for Microsoft IIS. Implementing CVM service requires the following tasks: Obtaining the CVM files Installing and configuring the CVM for your Web server Configuring OCSP and additional installation requirements (optional) During CVM installation, important information is written to the log file you specify in the valconfig.exe configuration utility (for example, C:\VeriSign\cvm\logs\cvm.log). Additionally, look at the Windows event log for possible errors logged by IIS. This information is useful for ensuring that the CVM is installed correctly. Consult these log files if problems arise. Obtaining the CVM files The CVM software is available from the Download page in the Managed PKI Control Center. The Control Center is regularly updated with the latest version of CVM. Be sure to download the correct CVM for your operating system. BT38-MPKI6-CVM-V1.0 9

16 Managed PKI Certificate Validation and Parsing Guide Step 1 Step 2 Unzip the software Open the contents of the Microsoft IIS folder Figure 3-1 Microsoft IIS directory with subdirectories The top-level directory for the Microsoft IIS Web server includes the following subdirectories (Figure 3-1): bin: Contains the binary files that implement the CVM plug-in. certcache: Contains the root certificates. config: Contains the configuration files. Installing and Configuring the CVM for Your Web Server Install and configure your Microsoft IIS Web server by completing the following steps: Step 1 Step 2 Step 3 Stop the Web server Open the Microsoft Management Console and stop the Web server. Copy the subdirectories to the Web server Copy the three subdirectories from the win\server\cvm\iis directory (Figure 3-1) to C:\VeriSign\cvm. Configure the Web server to use the SSL protocol If you do not already have a Server Certificate for your Web server, you must obtain one before configuring the Web server. 10 BT38-MPKI6-CVM-V1.0

17 Chapter 3 Installing and Configuring the CVM Filter for Microsoft IIS Ensure that your Web server is configured to use the SSL protocol by completing the following steps: 1 Open the Directory Security tab on the Web site s Properties page. 2 In the Secure Communications section, click Edit. 3 Ensure that both the Require secure channel (SSL) when accessing this resource and Require client certificates check boxes are selected. These selections cause the server to ask the client browser for a certificate before continuing. 4 IIS version 5.0 or later is capable of performing its own revocation checking. For correct operation of CVM, turn off IIS s revocation checking so that it does not conflict with CVM. Refer to the Web server documentation for details. 5 If you are implementing CVM for Private Managed PKI, add your CA to the list of CAs trusted by IIS for client authentication. Refer to the Web server documentation for details. Step 4 Run the CVM configuration program (valconfig.exe) The valconfig.exe program enables you to write values into the Windows 2000/2003 registry. Run valconfig.exe located in C:\VeriSign\cvm\config\valConfig.exe. The valconfig dialog box appears (Figure 3-2). Refer to Appendix A, CVM Configuration Values for descriptions and values to use when running valconfig.exe. BT38-MPKI6-CVM-V1.0 11

18 Managed PKI Certificate Validation and Parsing Guide You must run this program before using the CVM filter. Figure 3-2 valconfig dialog box Step 5 Edit the Trust Configuration File (val_config.txt) The CVM filter is controlled by a configuration file that specifies where to acquire the intermediate CA certificates and CRLs required by the filter. This file is required; even if the filter is running in fully automatic mode, the configuration file specifies the root certificates for the filter. This file is specified in the cfg-filename entry as shown in Figure 3-2 and is located in C:\VeriSign\cvm\config\val_config.txt. The configuration file is case-sensitive. Signify comment lines with the # character. The configuration file consists of pairs of lines. The first line of the pair specifies the format for this certificate or CRL, and begins with the text ENTRY=. The second line specifies the location of the certificate or CRL, and begins with either READ= or READ_NO_PREFIX=. 12 BT38-MPKI6-CVM-V1.0

19 Chapter 3 Installing and Configuring the CVM Filter for Microsoft IIS ENTRY Line The ENTRY line describes the entry using three required strings and two optional strings. The line must use exactly one string from each of the following sets: {CERT, CRL}, {FILE, URL}, {DER, PKCS7}. This specifies whether the object is a certificate or CRL, whether it is a local file or a URL, and whether it is a DER/BER binary object or a PKCS#7 encoded object. In addition to these values, the entry line may optionally contain the string B64 to signify that the object has been Base64 encoded. To install CA root certificates into the CVM filter, and to instruct the filter to trust the root certificates, use the optional string ROOT. To use this option, the entry must be of CERT and FILE type (not of type URL). Use this option only for the root certificates in the server s certificate database. READ Line READ=<name> specifies the location of the certificate or CRL. If the entry is a file, the plug-in tries to open <file-prefix>/<name> (substituting the value of file-prefix from the plug-in configuration). If you use READ_NO_PREFIX=<name>, the plug-in opens name (without the prefix). Similarly for URLs, READ=<url> looks in <url-prefix>/<url> and READ_NO_PREFIX=<url> does not perform the substitution. Sample CVM Configuration File The following sample configuration file illustrates how to configure val_config.txt for Managed PKI Public and Managed PKI Private. This file is included in the CVM software as val_config.txt. IMPORTANT! If you are using Pilot Managed PKI, then your CRL is hosted at onsitecrl-test.trustwise.com. Ensure that you configure for Pilot Managed PKI by replacing all occurrences of onsitecrl.trustwise.com in the configuration file with onsitecrl-test.trustwise.com. MPKI Public Version # Begin Sample File ############################################ # For Production Platform # ############################################ BT38-MPKI6-CVM-V1.0 13

20 Managed PKI Certificate Validation and Parsing Guide # PCA2 ROOT (MPKI CA), uses file-prefix ENTRY=CERT FILE DER ROOT READ=pca2ss_g2.509 # PCA2 CRL, uses url-prefix. Note - Not normally required #ENTRY=CRL URL DER #READ_NO_PREFIX= # MPKI Public Intermediate(Signing) CA, uses file-prefix ENTRY=CERT FILE DER READ=publiconsite_g2.509 # MPKI Public Intermediate CRL ENTRY=CRL URL PKCS7 READ_NO_PREFIX= ############################################ # For Pre-Production Platform # ############################################ # Pilot MPKI CA, uses file-prefix #ENTRY=CERT FILE DER ROOT #READ=BTTW_class2_testroot.509 # Pilot MPKI Public Intermediate(Signing)CA, uses file-prefix #ENTRY=CERT FILE DER #READ=BTTW_class2_onsite_individual_test_ca.509 # Pilot MPKI Public Signing CA CRL #ENTRY=CRL URL PKCS7 #READ_NO_PREFIX= L ############################################ # For Testdrive Platform # ############################################ # TestDrive CA, uses file-prefix #ENTRY=CERT FILE DER ROOT #READ=BTTW_onsite_sub_demo.509 # TestDrive CA CRL #ENTRY=CRL URL PKCS7 #READ_NO_PREFIX= # End Sample File 14 BT38-MPKI6-CVM-V1.0

21 Chapter 3 Installing and Configuring the CVM Filter for Microsoft IIS MPKI Private Version # Begin Sample File #Private CRL Checking CA ENTRY=CERT FILE DER B64 ROOT # replace $YOUR_PATH with the appropriate directory # that can be found by the web server and $YOUR_CA # with your CA's certificate in base64 format. READ_NO_PREFIX=$YOUR_PATH/$YOUR_CA.b64 # CRL ENTRY=CRL URL PKCS7 # The substring $YOUR_COMPANY should be replaced with the corresponding # string you see in the Control Centre s CRL Checker download # page. READ_NO_PREFIX= # End Sample File Step 6 Create the log directory Create the log directory that specified while running valconfig.exe. For example, for the log-file-name in Figure 3-2 on page 12 you would create: C:\VeriSign\cvm\logs. During the CVM installation, important information is written to the log file you specify in the valconfig.exe configuration utility. This information is useful for ensuring the CVM is installed correctly. Consult these log files if problems arise. Step 7 Install the CVM filter in the IIS server Install the CVM filter in the Web server as either a local filter (recommended) or as a global filter. Note Installing the CVM as a global filter applies the CVM filter as a global filter on all Web servers on this computer. BT38-MPKI6-CVM-V1.0 15

22 Managed PKI Certificate Validation and Parsing Guide Installing the CVM as a local filter (recommended) Install the CVM as a local filter in the Web server as follows: 1 Right-click the Default Web Site icon and select Properties for the Web server. 16 BT38-MPKI6-CVM-V1.0

23 Chapter 3 Installing and Configuring the CVM Filter for Microsoft IIS 2 Click the ISAPI Filters tab. 3 Click Add. 4 Enter validate for the Filter Name. 5 Enter C:\VeriSign\cvm\bin\libvsvalm.dll for the Executable. 6 Click OK. 7 Close the Properties page. BT38-MPKI6-CVM-V1.0 17

24 Managed PKI Certificate Validation and Parsing Guide Installing the CVM as a global filter for IIS 5.0. Install the CVM as a global filter in the Web server as follows: 1 In the IIS Console, right-click the computer icon and select Properties. 18 BT38-MPKI6-CVM-V1.0

25 Chapter 3 Installing and Configuring the CVM Filter for Microsoft IIS 2 In the Master Properties section of the resulting dialog box, select WWW Service. 3 Click Edit. BT38-MPKI6-CVM-V1.0 19

26 Managed PKI Certificate Validation and Parsing Guide 4 Click the ISAPI Filters tab. 5 Click Add. 6 Enter validate for the Filter Name. 7 Enter C:\VeriSign\cvm\bin\libvsvalm.dll for the Executable. 8 Click OK. 9 Close the Properties page. Installing the CVM as a global filter for IIS 6.0. Install the CVM as a global filter in the Web server as follows: 20 BT38-MPKI6-CVM-V1.0

27 Chapter 3 Installing and Configuring the CVM Filter for Microsoft IIS 1 In IIS Manager, right-click the Web Sites and select Properties. 2 Click the ISAPI Filters tab. 3 Click Add. 4 Enter validate for the Filter Name. 5 Enter C:\VeriSign\cvm\bin\libvsvalm.dll for the Executable. 6 Click OK. 7 Close the Properties page. BT38-MPKI6-CVM-V1.0 21

28 Managed PKI Certificate Validation and Parsing Guide Step 8 Start the Web server Stop and start the IIS Administrator Service and the World Wide Web Publishing Service from your Services Control Panel. Verify that the CVM has started as follows: 1 Right-click the Default Web Site icon and select Properties. 2 Click the ISAPI Filters tab. Ensure that there is a green up arrow (for Status) as shown here. 22 BT38-MPKI6-CVM-V1.0

29 Chapter 3 Installing and Configuring the CVM Filter for Microsoft IIS Note If there is a red down arrow (for Status), refer to Authentication Services Error Codes and Troubleshooting Guide. 3 Ensure that there are no errors written to the log file that you specified in valconfig.exe. If that file does not exist or is not up-to-date, complete the following step: Stop the server and stop the Web Publishing Service (this ensures that the file is flushed to disk). Check for the log file again. You may find further clues in the system event log. If the file is still not there, make sure you followed all of the steps to configure your Microsoft IIS correctly. If the file is still not there, look in the System Event log. If IIS fails to load the filter, it will log the failure in the System Event log. If your Web Server fails to start, refer to Authentication Services Error Codes and Troubleshooting Guide for help. BT38-MPKI6-CVM-V1.0 23

30 Managed PKI Certificate Validation and Parsing Guide Step 9 Test the implementation by performing transactions Access your protected Web site with valid and invalid certificates. Successful transactions generate an access message. Unsuccessful transactions result in a security message. You can configure CVM so that both types of transaction are logged into the log file. The certificate status and subject name appear in the message. Filter error (and optionally, informational) messages are also written into the log file. Optional: Configuring OCSP and Additional Installation Requirements The CVM is now configured to run CRL status checking on an installation using the default settings.the optional configurations listed in this section enable the CVM for OCSP service and to configure the CVM to fit your specific installation requirements. CVM and OCSP Service By default, the CVM is configured to run CRL status checking. You can enable CVM for OCSP service using the procedures in Enabling the CVM for OCSP Service in Chapter 8. You can enable CVM with CRL checking or OCSP, but not both. Configuring CVM to Fit Other Installation Requirements If you did not use the default values to install the CVM, then you must specify the CVM configuration values in the obj.conf file. See Appendix A, CVM Configuration Values. IMPORTANT! Use only the options that are appropriate for your implementation. For example, use either url-prefix= <value> or ocsp-url= <value>. Do not use both. Some options are used by Microsoft IIS only (noted in the Description column of Table A-1 in Appendix A, CVM Configuration Values ). 24 BT38-MPKI6-CVM-V1.0

31 re t pahc CHAPTER 4 4Installing and Configuring the CVM Filter for Microsoft ISA Server This chapter describes the procedures for obtaining, installing, and configuring the CVM filter for Microsoft ISA (Internet Security and Acceleration) server. Implementing CVM service involves the following tasks: Obtaining the CVM files Installing and configuring the CVM for your server Configuring OCSP and additional installation requirements (optional) During the CVM installation, important information is written to the log file that you specify in the valconfig.exe configuration utility (for example, C:\VeriSign\cvm\logs\cvm.log). Additionally, look at the Windows event log for possible errors logged by ISA server. This information is useful for ensuring the CVM is installed correctly. Consult these log files if problems arise. Obtaining the CVM files The CVM software is available from the Download page in the Managed PKI Control Center. The Control Center is regularly updated with the latest version of CVM. Be sure to download the correct CVM for your operating system. BT38-MPKI6-CVM-V1.0 25

32 Managed PKI Certificate Validation and Parsing Guide Step 1 Step 2 Unzip the software Open the contents of the Microsoft IIS folder Figure 4-1 Microsoft IIS directory with subdirectories There is a top-level directory for the Microsoft IIS Web server with the following subdirectories (Figure 4-1): bin: Contains the binary files that implement the CVM filter. certcache: Contains the root certificates. config: Contains the configuration files. Note The top level directory for Microsoft IIS Web server and Microsoft ISA server is same. Installing and Configuring the CVM for Your Web Server Install and configure your Microsoft ISA Web server by completing the following steps: Step 1 Step 2 Stop the Web server Open the Microsoft ISA Management Console and stop the Web proxy service. Unzip the CVM software and copy the subdirectories to the ISA server Copy the three subdirectories from the Nt\server\cvm\iis directory (Figure 4-1) to C:\VeriSign\cvm 26 BT38-MPKI6-CVM-V1.0

33 Chapter 4 Installing and Configuring the CVM Filter for Microsoft ISA Server Copy the plug-in dlls from win\server\cvm\iis\bin\ into the ISA installation directory (for example, c:\program Files\Microsoft ISA Server) Step 3 Step 4 Configure the ISA Web Proxy Server to use the SSL protocol If you do not already have a Server Certificate for your Web server, you must obtain one before configuring the Web server. Ensure that your Web server is configured to use the SSL protocol by completing the following steps: a b c d In the Microsoft ISA Management Console, select the properties for your server. Click the Incoming Web Request tab. Select the Listener and edit its properties. Select the server certificate by clicking Select. Ensure that both the Use a server certificate to authenticate to web clients and Client certificate (secure channel only) checkboxes are selected. Select both the Enable SSL listeners and Ask unauthenticated users for authentication check boxes. These selections ensure that the server uses the SSL protocol and requests a certificate from the client browser before continuing. Run the CVM configuration program (valconfig.exe) The valconfig.exe program enables you to write values into the Windows 2000/2003 registry. Run the valconfig.exe program located in C:\VeriSign\cvm\config\valConfig.exe. The valconfig dialog box appears BT38-MPKI6-CVM-V1.0 27

34 Managed PKI Certificate Validation and Parsing Guide (Figure 4-2). Refer to Appendix A, CVM Configuration Values, for descriptions and values to use when running valconfig.exe. Select Yes for the isa-install option You must run this program before using the CVM filter. Figure 4-2 valconfig dialog box Step 5 Edit the trust configuration file (val_config.txt) The CVM filter is controlled by a configuration file that specifies where to acquire the intermediate CA certificates and CRLs required by the filter. This file is required; even if the filter is running in fully automatic mode, the configuration file specifies the root certificates for the filter. This file is specified in the cfg-filename entry as shown in Figure 4-2 and is located in C:\VeriSign\cvm\config\val_config.txt. The configuration file is case-sensitive. Signify comment lines with the # character. 28 BT38-MPKI6-CVM-V1.0

35 Chapter 4 Installing and Configuring the CVM Filter for Microsoft ISA Server The configuration file consists of pairs of lines. The first line of the pair specifies the format for this certificate or CRL, and begins with the text ENTRY=. The second line specifies the location of the certificate or CRL, and begins with either READ= or READ_NO_PREFIX=. ENTRY Line The ENTRY line describes the entry using three required strings and two optional strings. The line must use exactly one string from each of the following sets: {CERT, CRL}, {FILE, URL}, {DER, PKCS7}. This specifies whether the object is a certificate or CRL, whether it is a local file or a URL, and whether it is a DER/BER binary object or a PKCS#7 encoded object. In addition to these values, the entry line may optionally contain the string B64 to signify that the object has been Base64 encoded. To install CA root certificates into the CVM filter, and to instruct the filter to trust the root certificates, use the optional string ROOT. To use this option, the entry must be of CERT and FILE type (not of type URL). Use this option only for the root certificates in the server s certificate database. READ Line READ=<name> specifies the location of the certificate or CRL. If the entry is a file, the plug-in tries to open <file-prefix>/<name> (substituting the value of file-prefix from the plug-in configuration). If you use READ_NO_PREFIX=<name>, the plug-in opens name (without the prefix). Similarly for URLs, READ=<url> looks in <url-prefix>/<url> and READ_NO_PREFIX=<url> does not perform the substitution. Sample CVM Configuration File The following sample configuration file illustrates how to configure val_config.txt for Managed PKI Public and Managed PKI Private. This file is included in the CVM software as val_config.txt. IMPORTANT! If you are using Pilot Managed PKI, then your CRL is hosted at onsitecrl-test.trustwise.com. Ensure that you configure for Pilot Managed PKI by replacing all occurrences of onsitecrl.trustwise.com in the configuration file with onsitecrl-test.trustwise.com. BT38-MPKI6-CVM-V1.0 29

36 Managed PKI Certificate Validation and Parsing Guide MPKI Public Version # Begin Sample File ############################################ # For Production Platform # ############################################ # PCA2 ROOT (MPKI CA), uses file-prefix ENTRY=CERT FILE DER ROOT READ=pca2ss_g2.509 # PCA2 CRL, uses url-prefix. Note - Not normally required #ENTRY=CRL URL DER #READ_NO_PREFIX= # MPKI Public Intermediate(Signing) CA, uses file-prefix ENTRY=CERT FILE DER READ=publiconsite_g2.509 # MPKI Public Intermediate CRL ENTRY=CRL URL PKCS7 READ_NO_PREFIX= ############################################ # For Pre-Production Platform # ############################################ # Pilot MPKI CA, uses file-prefix #ENTRY=CERT FILE DER ROOT #READ=BTTW_class2_testroot.509 # Pilot MPKI Public Intermediate(Signing)CA, uses file-prefix #ENTRY=CERT FILE DER #READ=BTTW_class2_onsite_individual_test_ca.509 # Pilot MPKI Public Signing CA CRL #ENTRY=CRL URL PKCS7 #READ_NO_PREFIX= ############################################ # For Testdrive Platform # ############################################ # TestDrive CA, uses file-prefix #ENTRY=CERT FILE DER ROOT #READ=BTTW_onsite_sub_demo.509 # TestDrive CA CRL #ENTRY=CRL URL PKCS7 #READ_NO_PREFIX= # End Sample File 30 BT38-MPKI6-CVM-V1.0

37 Chapter 4 Installing and Configuring the CVM Filter for Microsoft ISA Server MPKI Private Version # Begin Sample File #Private CRL Checking CA ENTRY=CERT FILE DER B64 ROOT # replace $YOUR_PATH with the appropriate directory # that can be found by the web server and $YOUR_CA # with your CA's certificate in base64 format. READ_NO_PREFIX=$YOUR_PATH/$YOUR_CA.b64 # CRL ENTRY=CRL URL PKCS7 # The substring $YOUR_COMPANY should be replaced with the corresponding # string you see in the MPKI Control Centre s CRL Checker download # page. READ_NO_PREFIX= # End Sample File Step 6 Create the log directory Create the log directory that specified while running valconfig.exe. For example, for the log-file-name in Figure 3-2 on page 12 you would create: C:\VeriSign\cvm\logs. During the CVM installation, important information is written to the log file you specify in the valconfig.exe configuration utility. This information is useful for ensuring the CVM is installed correctly. Consult these log files if problems arise. Step 7 Step 8 Install the CVM Web filter in the ISA server Use the sample Visual Basic script cvmregister.vbs (provided along with package) to register the CVM plug-in in the ISA Server. You can change the priority and direction in this script as per your requirement. The default priority is Medium and direction is Incoming Web Requests. Restart the Web Proxy service in the ISA server BT38-MPKI6-CVM-V1.0 31

38 Managed PKI Certificate Validation and Parsing Guide Step 9 Test the implementation by performing transactions Access your protected Web site with valid and invalid certificates. Successful transactions generate an access message. Unsuccessful transactions result in a security message. You can configure CVM so that both types of transaction are logged into the log file. The certificate status and subject name appear in the message. Filter error (and optionally, informational) messages are also written into the log file. Configuring OCSP and Additional Installation Requirements (Optional) The CVM is now configured to run CRL status checking on an installation using the default settings. The optional configurations listed in this section enable the CVM for OCSP service and to configure the CVM to fit your specific installation requirements. CVM and OCSP Service By default, the CVM is configured to run CRL status checking. You can enable CVM for OCSP service using the procedures in Enabling the CVM for OCSP Service in Chapter 8. You can enable CVM with CRL checking or OCSP, but not both. Configuring the CVM to Fit Other Installation Requirements If you did not use the default values to install the CVM, configuring the CVM to fit other installations requires that you configure those values using the valconfig.exe configuration utility with the values described in Appendix A, CVM Configuration Values. IMPORTANT! Use only the options that are appropriate for your implementation. For example, use either url-prefix= <value> or ocsp-url= <value>. Do not use both. Some options are used by Microsoft IIS only (noted in the Description column of Table A-1 in Appendix A, CVM Configuration Values ). 32 BT38-MPKI6-CVM-V1.0

39 re t pahc CHAPTER 5 5Installing and Configuring the CVM Plug-In for SunONE Enterprise Server This chapter describes the procedures for obtaining, installing and configuring the CVM plug-in for SunONE Enterprise Server. Implementing CVM service requires the following tasks: Obtaining the CVM files Installing and configuring the CVM for your Web server Configuring OCSP and additional installation requirements (optional) During the CVM installation, important information is written to the server log file <server-base-dir>/logs/errors. This information is useful for ensuring the CVM is installed correctly. Consult these log files if problems arise. Obtaining the CVM files The CVM software is available from the Download page in the Managed PKI Control Center. (The Control Center is regularly updated with the latest version of CVM.) Be sure to download the correct CVM for your operating system. BT38-MPKI6-CVM-V1.0 33

40 Managed PKI Certificate Validation and Parsing Guide Step 1 Step 2 Unzip the software Open the contents of the Netscape folder Figure 5-1 Netscape directory with subdirectories There is a top level directory for the Netscape Web server with the following subdirectories (Figure 5-1): bin Contains the binary files that implement the CVM plug-in. certcache Contains the root certificates. config Contains the configuration files. Step 3 Copy the subdirectories to your Web server Copy the bin, certcache, and config subdirectories from the CVM software to your Web server using the appropriate platform location: Windows 2000/2003: C:\VeriSign\cvm HP-UX: /VeriSign/cvm Solaris: /VeriSign/cvm Installing and Configuring the CVM for Your Web Server Install and configure your SunONE Enterprise Server Web server by completing the following steps: 34 BT38-MPKI6-CVM-V1.0

41 Chapter 5 Installing and Configuring the CVM Plug-In for SunONE Enterprise Server Step 1 Step 2 Step 3 Copy the binaries to the Web server Follow the procedure appropriate to your platform: Windows 2000/2003: Copy the three *.dll files from the win\server\cvm\netscape\bin directory into a directory in which the Web server can find them. (Typically, \netscape\suitespot\bin\https or for SunONE servers, \netscape\server4\bin\https\bin.) HP-UX: Copy the three *.sl files from the HPUX/server/cvm/netscape/bin directory into a directory in which the Web server can find them. (Typically, /usr/local/lib or /usr/lib are good locations.) Alternatively, install the library elsewhere and modify SHLIB_PATH. Solaris: Copy the three *.so files from the Solaris/server/cvm/netscape/bin directory into a directory in which the Web server can find them. (Typically, /usr/local/lib or /usr/lib or for iplanet servers, /usr/netscape/server4/bin/https/lib.) Alternatively, install the library elsewhere and modify LD_LIBRARY_PATH. Stop the Web server Configure the Web server to use the SSL protocol If you do not already have a Server Certificate for your Web server, you must obtain one before configuring the Web server. Configure your Web server to use the SSL protocol. See the Web server documentation for details. Note Ensure that the Require client certificates check box is selected. Additionally, ensure that the CA issuing the client certificates is designated as a Trusted Client CA. Step 4 Edit the file For SunONE Enterprise Server 4.x, edit the SunONE Enterprise Server netscape\<suitespot Server4>\<server-name>\config\obj.conf file by completing the following steps: BT38-MPKI6-CVM-V1.0 35

42 Managed PKI Certificate Validation and Parsing Guide 1 Add the following two lines at the top, near the other Init fn lines. These lines instruct the Web server to load the plug-in and to run its initialization function. Definitions and values for the options are in Appendix A, CVM Configuration Values. Note The line breaks in the sample lines below occur only due to the limits of the width of the page. There are only two lines. Even if many options are used, they must all be placed in the same line. Do not put a space after commas or use the Enter key in either of the two lines. Init fn= load-modules funcs= vscheckcertinit,vscheckclientcert shlib= <value> Init fn= vscheckcertinit cfg-filename= <value> file-prefix= <value> url-prefix = <value> ocsp-url= <value> cache-dir= <value> log-security= <value> log-info = <value> default-ldap= <value> update-hours= <value> no-check-chain= <value> error-cgi= <value> http-proxy= <value> ldap-http-proxy= <value> Use only the options that are appropriate for your implementation. For example, use either url-prefix= <value> or ocsp-url= <value>. Do not use both, as shown (for placement purposes only) in the example. Some options are used by Microsoft IIS only (noted in the Description column of Table A-1 in Appendix A, CVM Configuration Values ). For example: Note For SunONe Server (on Windows or UNIX), use forward slashes. For Stronghold (on UNIX) use forward slashes. For IIS (on Windows) use back slashes. Init fn="load-modules" funcs="vscheckcertinit,vscheckclientcert" shlib= "c:/verisign/cvm/bin/libvsvaln.dll" Init fn="vscheckcertinit" cfg-filename="c:/verisign/cvm/config/val_con fig.txt" file-prefix="c:/verisign/cvm/certcache/" url-prefix=" onsitecrl.trustwise.com/onsitepublic/" cache-dir="c:/verisign/cvm/cert cache/" log-security="on" log-info="on" update-hours="24" no-check-chain ="on" For SunONE Enterprise Server 6.x, 36 BT38-MPKI6-CVM-V1.0

43 Chapter 5 Installing and Configuring the CVM Plug-In for SunONE Enterprise Server 1 Edit the <iplanet-install-dir>/<server-name>/config/magnus.conf file by adding the following lines to the end of the file: Note The line breaks in the sample lines below occur only due to the limits of the width of the page. There are only two lines. Even if many options are used, they must all be placed in the same line. Do not put a space after commas or use the Enter key in either of the two lines. For SunONE Server on Windows or UNIX, use forward slashes (/). Init fn="load-modules" funcs="vscheckcertinit,vscheckclient Cert" shlib= C:/netscape/server4/bin/https/bin/libvsvaln. dll Init fn="vscheckcertinit" cfg-filename="<value>" file-prefix ="<value>" url-prefix="<value>" ocsp-url="<value>" cache-dir ="<value>" log-security="<value>" log-info="<value>" defaultldap="<value>" update-hours="<value>" no-check-chain="<value> " error-cgi="<value> http-proxy="<value>" ldap-http-proxy=" <value>" LateInit="yes" Use only the options that are appropriate for your implementation. For example, use either url-prefix="<value>" or ocsp-url="<value>". Do not use both as shown in the example. Some options are used by Microsoft IIS/ISA only (noted in the Description column of Table A-1 in Appendix A, CVM Configuration Values ). Step 5 Turn on the authorization function Turn on the authorization function by adding the following line to the obj.conf file for the objects that are being protected: AuthTrans fn= vscheckclientcert To turn the authorization function on for all objects (the simplest method) add the line immediately after the <Object name=default> line. If the server already has a line that executes the get-client-cert function, remove it. The validation plug-in performs this step automatically. BT38-MPKI6-CVM-V1.0 37

44 Managed PKI Certificate Validation and Parsing Guide For example (added lines are in bold): <Object name=default> AuthTrans fn="vscheckclientcert" NameTrans fn=pfx2dir from=/ns-icons dir="d:/netscape/suitespot/ns-icons" AddLog fn=flex-log name="access" </Object> <Object name=cgi> ObjectType fn=force-type type=magnus-internal/cgi Service fn=send-cgi </Object> This authorization function (in bold) instructs the server to ask the client browser for a valid certificate, and performs revocation checking on it before allowing the transaction to complete. Step 6 Edit the Trust Configuration File (val_config.txt) The CVM filter is controlled by a configuration file that specifies where to acquire the intermediate CA certificates and CRLs required by the filter. This file is required; even if the filter is running in fully automatic mode, the configuration file specifies the root certificates for the filter. This file is specified in the cfg-filename entry as shown in Figure 3-2 and is located in C:\VeriSign\cvm\config\ val_config.txt. The configuration file is case-sensitive. Signify comment lines with the # character. The configuration file consists of pairs of lines. The first line of the pair specifies the format for this certificate or CRL, and begins with the text ENTRY=. The second line specifies the location of the certificate or CRL, and begins with either READ= or READ_NO_PREFIX=. ENTRY Line The ENTRY line describes the entry using three required strings and two optional strings. The line must use exactly one string from each of the following sets: {CERT, CRL}, {FILE, URL}, {DER, PKCS7}. This specifies whether the object 38 BT38-MPKI6-CVM-V1.0

45 Chapter 5 Installing and Configuring the CVM Plug-In for SunONE Enterprise Server is a certificate or CRL, whether it is a local file or a URL, and whether it is a DER/BER binary object or a pkcs7 encoded object. In addition to these values, the entry line may optionally contain the string B64 to signify that the object has been Base64 encoded. To install CA root certificates into the CVM filter, and to instruct the filter to trust the root certificates, use the optional string ROOT. To use this option, the entry must be of CERT and FILE type (not of type URL). Use this option only for the root certificates in the server s certificate database. READ Line READ=<name> specifies the location of the certificate or CRL. If the entry is a file, the plug-in tries to open <file-prefix>/<name> (substituting the value of file-prefix from the plug-in configuration). If you use READ_NO_PREFIX=<name>, the plug-in opens name (without the prefix). Similarly for URLs, READ=<url> looks in <url-prefix>/<url> and READ_NO_PREFIX=<url> does not perform the substitution. Sample CVM Configuration File The following sample configuration file illustrates how to configure val_config.txt for Managed PKI Public and Managed PKI Private. This file is included in the CVM software as val_config.txt. IMPORTANT! If you are using Pilot Managed PKI, then your CRL is hosted at onsitecrl-test.trustwise.com. Ensure that you configure for Pilot Managed PKI by replacing all occurrences of onsitecrl.trustwise.com in the configuration file with onsitecrl-test.trustwise.com. MPKI Public Version # Begin Sample File ############################################ # For Production Platform # ############################################ # PCA2 ROOT (MPKI CA), uses file-prefix ENTRY=CERT FILE DER ROOT READ=pca2ss_g2.509 # PCA2 CRL, uses url-prefix. Note - Not normally required #ENTRY=CRL URL DER #READ_NO_PREFIX= BT38-MPKI6-CVM-V1.0 39

46 Managed PKI Certificate Validation and Parsing Guide # MPKI Public Intermediate(Signing) CA, uses file-prefix ENTRY=CERT FILE DER READ=publiconsite_g2.509 # MPKI Public Intermediate CRL ENTRY=CRL URL PKCS7 READ_NO_PREFIX= ############################################ # For Pre-Production Platform # ############################################ # Pilot MPKI CA, uses file-prefix #ENTRY=CERT FILE DER ROOT #READ=BTTW_class2_testroot.509 # Pilot MPKI Public Intermediate(Signing)CA, uses file-prefix #ENTRY=CERT FILE DER #READ=BTTW_class2_onsite_individual_test_ca.509 # Pilot MPKI Public Signing CA CRL #ENTRY=CRL URL PKCS7 #READ_NO_PREFIX= ############################################ # For Testdrive Platform # ############################################ # TestDrive CA, uses file-prefix #ENTRY=CERT FILE DER ROOT #READ=BTTW_onsite_sub_demo.509 # TestDrive CA CRL #ENTRY=CRL URL PKCS7 #READ_NO_PREFIX= # End Sample File MPKI Private Version # Begin Sample File #Private CRL Checking CA ENTRY=CERT FILE DER B64 ROOT # replace $YOUR_PATH with the appropriate directory # that can be found by the web server and $YOUR_CA # with your CA's certificate in base64 format. READ_NO_PREFIX=$YOUR_PATH/$YOUR_CA.b64 # CRL ENTRY=CRL URL PKCS7 40 BT38-MPKI6-CVM-V1.0

47 Chapter 5 Installing and Configuring the CVM Plug-In for SunONE Enterprise Server # The substring $YOUR_COMPANY should be replaced with the corresponding # string you see in the MPKI Control Centre s CRL Checker download # page. READ_NO_PREFIX= # End Sample File Step 7 Step 8 Start the Web server Test the implementation by performing transactions Access your protected Web site with valid and invalid certificates. Successful transactions generate an access message. Unsuccessful transactions result in a security message. You can configure CVM so that both types of transaction are logged into the log file. The certificate status and subject name appear in the message. Filter error (and optionally, informational) messages are also written into the log file. Optional: Configuring OCSP and Additional Installation Requirements The CVM is now configured to run CRL status checking on an installation using the default settings.the optional configurations listed in this section enable the CVM for OCSP service and to configure the CVM to fit your specific installation requirements. CVM and OCSP Service By default, the CVM is configured to run CRL status checking. You can enable CVM for OCSP service using the procedures in Enabling the CVM for OCSP Service in Chapter 8. You can enable CVM with CRL checking or OCSP, but not both. Configuring the CVM to Fit Other Installation Requirements If you did not use the default values to install the CVM, then you must specify the CVM configuration values in the obj.conf file. See Appendix A, CVM Configuration Values. BT38-MPKI6-CVM-V1.0 41

48 Managed PKI Certificate Validation and Parsing Guide IMPORTANT! Use only the options that are appropriate for your implementation. For example, use either url-prefix= <value> or ocsp-url= <value>. Do not use both. Some options are used by Microsoft IIS only (noted in the Description column of Table A-1 in Appendix A, CVM Configuration Values ). 42 BT38-MPKI6-CVM-V1.0

49 re t pahc CHAPTER 6 6Installing and Configuring the CVM Module for Stronghold Secure Web Server This chapter describes the procedures for obtaining, installing and configuring the CVM module for the Stronghold Secure Web server. Implementing CVM service requires the following tasks: Obtaining the CVM files Installing and configuring the CVM for your Web server Configuring OCSP and additional installation requirements (optional) During the CVM installation, important information is written to the server log file <stronghold-dir>/logs/error_log and <stronghold-dir>/logs/ssl/error_log. This information is useful for ensuring the CVM is installed correctly. Consult these log files if problems arise. Obtaining the CVM files The CVM software is available from the Download page in the Managed PKI Control Center. The Control Center is regularly updated with the latest version of CVM. Be sure to download the correct CVM for your operating system. BT38-MPKI6-CVM-V1.0 43

50 Managed PKI Certificate Validation and Parsing Guide Step 1 Step 2 Unzip the software Open the contents of the Stronghold folder Figure 6-1 Stronghold directory with subdirectories The top-level directory for the Microsoft IIS Web server includes the following subdirectories (Figure 6-1): bin Contains the binary files that implement the CVM plug-in. certcache Contains the root certificates. config Contains the configuration files. Step 3 Copy the subdirectories to the Web server Copy the bin, certcache and config subdirectories from the CVM software to /VeriSign/cvm in your Web server. 44 BT38-MPKI6-CVM-V1.0

51 Chapter 6 Installing and Configuring the CVM Module for Stronghold Secure Web Server Installing and Configuring the CVM for Your Web Server Install and configure your Stronghold Web server by completing the following steps: Step 1 Step 2 Stop the Web server Copy the binaries to the Web server HP-UX Copy the three *.sl files from the HPUX/server/cvm/stronghold/bin directory into a directory in which the Web server can find them. (Typically, <stronghold-dir>/modules/libexec is a good location.) Alternatively, install the library elsewhere and modify SHLIB_PATH. Solaris Copy the three *.so files from the Solaris/server/cvm/stronghold/bin directory into a directory in which the Web server can find them. (Typically, <stronghold-dir>/modules/libexec is a good location.) Alternatively, install the library elsewhere and modify LD_LIBRARY_PATH. Step 3 Configure the Web server to use the SSL protocol If you do not already have a Server Certificate for your Web server, you must obtain one before configuring the Web server. Ensure that your Web server is configured to use the SSL protocol. See the Web server documentation for details. BT38-MPKI6-CVM-V1.0 45

52 Managed PKI Certificate Validation and Parsing Guide Step 4 Edit the configuration file Edit the <stronghold-dir>/conf/httpd.conf file as follows: 1 Configure the server to load the CVM module by adding the following line immediately after the existing load module directives in the configuration file (see Example of httpd.conf file on page 48): LoadModule vsval_module modules/libexec/mod_vsval.s 2 Clear the module list and add the modules for your server in the correct order. Configure the SSL module to be after the CVM module (mod_vsval.c) in the AddModule directive. Details about the currently configured modules in your server appear at: For example: AddModule mod_env.c mod_log_config.c mod_log_agent.c mod_cgi.c mod_so.c mod_vsval.c mod_ssl.c Note VeriSign s mod_so.c enables DSO support for loading the CVM module. 3 Specify the configuration values for the CVM module. Use the VSVAL_SetOpt directive to configure your CVM module. A complete list of values appears in Appendix A, CVM Configuration Values. <IfModule mod_vsval.c> VSVAL_ProtectAll off VSVAL_SetOpt file-prefix /VeriSign/cvm/certcache/ VSVAL_SetOpt log-info on... </IfModule> 4 Setting the LogLevel controls the number of messages logged to the error_log. Possible values include: debug, info, notice, warn, error, crit, # alert, emerg. For normal operation, use notice. Note The CVM module writes debugging information to the server log files based upon the LogLevel setting. LogLevel is an httpd.conf directive. 46 BT38-MPKI6-CVM-V1.0

53 Chapter 6 Installing and Configuring the CVM Module for Stronghold Secure Web Server 5 Set the Certificate Authority (CA) verification path to find one large file containing all of the CA certificates for client authentication (file must be PEM-encoded). If you are using Private Managed PKI, then add your CA to this file. For example: SSLCACertificateFile /usr/stronghold/ssl/ca/client-rootce rts.pem 6 Enable client authentication for your Web server. For example: SSLVerifyClient require SSLVerifyDepth 10 7 Optional: To protect an individual directory in a Stronghold Virtual Host, you must load the following entry after the last SSL configuration entry for any virtual host that needs to have a CVM-protected directory. If you are not using virtual hosts, then this entry is loaded globally in the default configuration. <IfModule mod_vsval.c> VSVAL_ProtectAll off VSVAL_SetOpt file-prefix /VeriSign/cvm/certcache/ VSVAL_SetOpt log-info on VSVAL_SetOpt cache-dir /VeriSign/cvm/certcache/ VSVAL_SetOpt log-security on VSVAL_SetOpt no-check-chain on VSVAL_SetOpt url-prefix c/ VSVAL_SetOpt cfg-filename /VeriSign/cvm/config/val_config.txt VSVAL_SetOpt update-hours 24 </IfModule> 8 Set the SSL engine options to enable certificate data to be exported: SSLOptions +ExportCertData BT38-MPKI6-CVM-V1.0 47

54 Managed PKI Certificate Validation and Parsing Guide Note You must enable certificate data to be exported for the CVM to work. 9 Protect the entire server or specific URLs using the VSVAL_ProtectAll or VSVAL_ProtectDir directives. VSVAL_ProtectAll is the default setting. If you want to protect only specific directories, turn off VSVAL_ProtectAll and use VSVAL_ProtectDir. See the following example for usage. Note In the case of using virtual hosts, either of these directives (VSVAL_ProtectAll or VSVAL_ProtectDir) must be set for each server instance that uses CVM protection. Example of httpd.conf file This example an entire httpd.conf file is intended to provide a holistic view of the configurations in Step 4, Edit the configuration file. # Example: # LoadModule foo_module libexec/mod_foo.so # LoadModule vsval_module modules/libexec/mod_vsval.so ClearModuleList AddModule mod_env.c mod_log_config.c mod_log_agent.c mod_log_referer.c mod_mime.c mod_negotiation.c mod_status.c mod_info.c mod_include.c mod_autoindex.c mod_dir.c mod_cgi.c mod_asis.c mod_imap.c mod_actions.c mod_userdir.c mod_alias.c mod_rewrite.c mod_access.c mod_auth.c mod_auth_dbm.c mod_proxy.c mod_cern_meta.c mod_expires.c mod_headers.c mod_usertrack.c mod_unique_id.c mod_so.c mod_setenvif.c mod_perl.c mod_vsval.c mod_ssl.c <IfModule mod_vsval.c> VSVAL_ProtectAll off VSVAL_SetOpt file-prefix /VeriSign/cvm/certcache/ VSVAL_SetOpt log-info on VSVAL_SetOpt cache-dir /VeriSign/cvm/certcache/ VSVAL_SetOpt log-security on VSVAL_SetOpt no-check-chain on VSVAL_SetOpt url-prefix c/ VSVAL_SetOpt cfg-filename /VeriSign/cvm/config/val_config.txt VSVAL_SetOpt update-hours BT38-MPKI6-CVM-V1.0

55 Chapter 6 Installing and Configuring the CVM Module for Stronghold Secure Web Server </IfModule>... ### Section 2: 'Main' server configuration #... # # LogLevel: Control the number of messages logged to the error_log. # Possible values include: debug, info, notice, warn, error, crit, # alert, emerg. # LogLevel info... ## ## SSL Global Context ## ## ## SSL Virtual Host Context ##... <VirtualHost _default_:443> # General setup for the virtual host... # Certificate Authority (CA): # Set the CA certificate verification path where to find CA # certificates for client authentication or alternatively one # huge file containing all of them (file must be PEM encoded) # Note: Inside SSLCACertificatePath you need hash symlinks # to point to the certificate files. Use the provided # Makefile to update the hash symlinks after changes. #SSLCACertificatePath /home/atulshibagwale/stronghold/conf/ssl.crt SSLCACertificateFile /home/atulshibagwale/stronghold/ssl/ca/client-rootcerts.pem... # SSL Engine Options: # Set various options for the SSL engine. # o ExportCertData: # This exports two additional environment variables: SSL_CLIENT_CERT and # SSL_SERVER_CERT. These contain the PEM-encoded certificates of the # server (always existing) and the client (only existing when client # authentication is used). This can be used to import the certificates # into CGI scripts. BT38-MPKI6-CVM-V1.0 49

56 Managed PKI Certificate Validation and Parsing Guide... SSLOptions +ExportCertData... </VirtualHost>... Alias /protected /myapplication/htmldocs <Location /protected> VSVAL_ProtectDir on SSLRequireSSL </Location> Step 5 Edit the Trust Configuration File (val_config.txt) The CVM filter is controlled by a configuration file that specifies where to acquire the intermediate CA certificates and CRLs required by the filter. This file is required; even if the filter is running in fully automatic mode, the configuration file specifies the root certificates for the filter. This file is specified in the cfg-filename entry as shown in Figure 3-2 and is located in C:\VeriSign\cvm\config\ val_config.txt. The configuration file is case-sensitive. Signify comment lines with the # character. The configuration file consists of pairs of lines. The first line of the pair specifies the format for this certificate or CRL, and begins with the text ENTRY=. The second line specifies the location of the certificate or CRL, and begins with either READ= or READ_NO_PREFIX=. ENTRY Line The ENTRY line describes the entry using three required strings and two optional strings. The line must use exactly one string from each of the following sets: {CERT, CRL}, {FILE, URL}, {DER, PKCS7}. This specifies whether the object is a certificate or CRL, whether it is a local file or a URL, and whether it is a DER/BER binary object or a pkcs7 encoded object. In addition to these values, the entry line may optionally contain the string B64 to signify that the object has been Base64 encoded. To install CA root certificates into the CVM filter, and to instruct the filter to trust the root certificates, use the optional string ROOT. To use this option, the entry must be of CERT and FILE type (not of type URL). Use this option only for the root certificates in the server s certificate database. 50 BT38-MPKI6-CVM-V1.0

57 Chapter 6 Installing and Configuring the CVM Module for Stronghold Secure Web Server READ Line READ=<name> specifies the location of the certificate or CRL. If the entry is a file, the plug-in tries to open <file-prefix>/<name> (substituting the value of file-prefix from the plug-in configuration). If you use READ_NO_PREFIX=<name>, the plug-in opens name (without the prefix). Similarly for URLs, READ=<url> looks in <url-prefix>/<url> and READ_NO_PREFIX=<url> does not perform the substitution. Sample CVM Configuration File The following sample configuration file illustrates how to configure val_config.txt for Managed PKI Public and Managed PKI Private. This file is included in the CVM software as val_config.txt. IMPORTANT! If you are using Pilot Managed PKI, then your CRL is hosted at onsitecrl-test.trustwise.com. Ensure that you configure for Pilot Managed PKI by replacing all occurrences of onsitecrl.trustwise.com in the configuration file with onsitecrl-test.trustwise.com.managed PKI Public Version MPKI Public Version # Begin Sample File ############################################ # For Production Platform # ############################################ # PCA2 ROOT (MPKI CA), uses file-prefix ENTRY=CERT FILE DER ROOT READ=pca2ss_g2.509 # PCA2 CRL, uses url-prefix. Note - Not normally required #ENTRY=CRL URL DER #READ_NO_PREFIX= # MPKI Public Intermediate(Signing) CA, uses file-prefix ENTRY=CERT FILE DER READ=publiconsite_g2.509 # MPKI Public Intermediate CRL ENTRY=CRL URL PKCS7 READ_NO_PREFIX= ############################################ # For Pre-Production Platform # ############################################ BT38-MPKI6-CVM-V1.0 51

58 Managed PKI Certificate Validation and Parsing Guide # Pilot MPKI CA, uses file-prefix #ENTRY=CERT FILE DER ROOT #READ=BTTW_class2_testroot.509 # Pilot MPKI Public Intermediate(Signing)CA, uses file-prefix #ENTRY=CERT FILE DER #READ=BTTW_class2_onsite_individual_test_ca.509 # Pilot MPKI Public Signing CA CRL #ENTRY=CRL URL PKCS7 #READ_NO_PREFIX= ############################################ # For Testdrive Platform # ############################################ # TestDrive CA, uses file-prefix #ENTRY=CERT FILE DER ROOT #READ=BTTW_onsite_sub_demo.509 # TestDrive CA CRL #ENTRY=CRL URL PKCS7 #READ_NO_PREFIX= # End Sample File MPKI Private Version # Begin Sample File #Private CRL Checking CA ENTRY=CERT FILE DER B64 ROOT # replace $YOUR_PATH with the appropriate directory # that can be found by the web server and $YOUR_CA # with your CA's certificate in base64 format. READ_NO_PREFIX=$YOUR_PATH/$YOUR_CA.b64 # CRL ENTRY=CRL URL PKCS7 # The substring $YOUR_COMPANY should be replaced with the corresponding # string you see in the MPKI Control Centre s CRL Checker download # page. READ_NO_PREFIX= # End Sample File 52 BT38-MPKI6-CVM-V1.0

59 Chapter 6 Installing and Configuring the CVM Module for Stronghold Secure Web Server Step 6 Step 7 Start the Web server If your web server fails to start, refer to Authentication Services Error Codes and Troubleshooting Guide for help. Test the implementation by performing transactions Access your protected Web site with valid and invalid certificates. Successful transactions generate an access message. Unsuccessful transactions result in a security message. You can configure CVM so that both types of transaction are logged into the log file. The certificate status and subject name appear in the message. Filter error (and optionally, informational) messages are also written into the log file. Module error (and optionally, informational) messages are also written into the server s error log. Be sure to look in the <stronghold-dir>/logs/error-log and stronghold-dir>/logs/ssl/error-log files for these errors. Optional: Configuring OCSP and Additional Installation Requirements The CVM is now configured to run CRL status checking on an installation using the default settings.the optional configurations listed in this section enable the CVM for OCSP service and to configure the CVM to fit your specific installation requirements. CVM and OCSP Service By default, the CVM is configured to run CRL status checking. You can enable CVM for OCSP service using the procedures in Enabling the CVM for OCSP Service in Chapter 8. You can enable CVM with CRL checking or OCSP, but not both. Configuring CVM to Fit Other Installation Requirements If you did not use the default values to install the CVM, then you must specify the CVM configuration values in the obj.conf file. See Appendix A, CVM Configuration Values. BT38-MPKI6-CVM-V1.0 53

60 Managed PKI Certificate Validation and Parsing Guide IMPORTANT! Use only the options that are appropriate for your implementation. For example, use either url-prefix= <value> or ocsp-url= <value>. Do not use both. Some options are used by Microsoft IIS only (noted in the Description column of Table A-1 in Appendix A, CVM Configuration Values ). 54 BT38-MPKI6-CVM-V1.0

61 re t pahc CHAPTER 7 7VeriSign Certificate Parsing Module (CPM) VeriSign s Certificate Parsing Module (CPM) software suite extracts fields from (parses) client certificates presented to the Web server and makes that information available to certificate-enabled applications. There are two CPM implementations, the server plug-in version and the programmer s library version. The library of CPM APIs allows you to extract fields from client certificates using your custom program. This chapter describes CPM s components and functions, as well as the hardware and software requirements for using CPM. This chapter also provides installation and configuration procedures for CPM. Components of the CPM Software Suite The Certificate Parsing Module software suite contains the following files: File Name libcdrn3.so and libcdrn3.sl and cdrn3.dll egcdr.pl egnsapicdr.c Description CPM server plug-in for iplanet Enterprise servers. (In this document, we use the generic name cdrplugin.so) Example CGI in Perl using CPM server plug-in. This CGI can be used to see certificate variables populated by the CPM plug-in. In the first line of the Perl script set the path to where the Perl executable is located. For example, #!/bin/perl. Example NSAPI in C for use with server plug-in; uses the CPM API. BT38-MPKI6-CVM-V1.0 55

62 Managed PKI Certificate Validation and Parsing Guide File Name libcdr.so and libcdr.sl and cdr.dll cdr.h cdrmain.c extparser.h Description (Continued) CPM programmer s library C/C++ header file for use with programmer s library C/C++ example for use with programmer s library C/C++ header for use with programmer s library Fields Extracted by CPM CPM can extract the following fields from a certificate: Certificate Field This Field Describes Description Name Subject Common name Subject address Address Subject Street address Title Subject The subject s professional title Unique ID Certificate Identifier unique to this certificate (typically the certificate serial number) Organization Subject The subject s Organization (typically the name of the enterprise or government agency) Organization Unit Count Subject Number of OUs in the certificate Organization Unit Subject Organization Unit (OU) fields. The number of these fields is specified by the Subject Organization Unit Count field. Country Issuer Country Locality Issuer Locality CN Issuer Common name Organization Issuer The issuer s Organization (typically the name of the CA) Organization Unit Count Issuer Number of OUs in the CA certificate 56 BT38-MPKI6-CVM-V1.0

63 Chapter 7 VeriSign Certificate Parsing Module (CPM) Certificate Field This Field Describes Description Organization Unit Issuer Organization Unit (OU) fields in the CA certificate. The number of these fields is specified by the Issuer Organization Unit Count field. Not Before Certificate Beginning of certificate validity period Not After Certificate End of certificate validity period Note Not all certificates contain all of these fields. When a field is not present in the certificate, data is not returned. Not all versions of the CPM return all of these values. If the CPM does not return a particular field, upgrade to the latest version of CPM. Programmer s Library File CPM is available as a programmers library file for use with C, C++, and other programming languages. VeriSign provides example CGI programs that use the programmer s library file for C and C++. CPM Implementations VeriSign provides two CPM implementations: Server plug-in version (NSAPI) Programmer s library version shared-object (*.so) file for UNIX systems and a dynamic-linked-library (*.dll) in Microsoft Windows WIN32 systems For most sites, VeriSign recommends the server plug-in version (loaded at server startup and accessed during a client session) because it offers a considerably simpler interface and because it is upgraded by replacing a single file. The server plug-in can be used with any other server plug-ins and extensions such as servers, Javascript, CGI programs in any programming language (Perl, C, C++), NSAPI modules, and so on. BT38-MPKI6-CVM-V1.0 57

64 Managed PKI Certificate Validation and Parsing Guide Option 1: Configuring the Server Plug-in Version of CPM Step 1 Acquire a client certificate In this step, you instruct the server to securely acquire a client certificate from the browser (user) that is talking to the server. (See the SunONE Server documentation for more information on the get-client-cert function.) Modify the obj.conf file in your server configuration directory. Add the following line between the last PathCheck and the first ObjectType commands: PathCheck fn= get-client-cert method= * dorequest= 1 Step 2 Configure the CPM server plug-in 1 Instruct the server to use the VSUnwrapCertificate function of the cdrplugin.so server plug-in. Add the following line in the magnus.conf file in your server configuration directory: Init fn= load-modules shlib= cdrplugin.so funcs= VSUnwrapCertificate Note All Init functions should go to mangus.conf. 2 In this step, you instruct the server on when to use this plug-in. Add the following line within an Object definition. Typically, this line follows the PathCheck line mentioned in Step 1, Acquire a client certificate. (See the SunONE Server documentation to learn how to use Object definitions in the obj.conf file) ObjectType fn= VSUnwrapCertificate Option 2: Configuring the CPM Programmer s Library No additional configuration is required to use the CPM programmer s library. To use CGIs, you must enable CGI programs in your server. See the SunONE Server documentation for instructions. Using the Server Plug-In The CPM server plug-in parses the contents of the client s certificate (if present in the server) and copies it into two locations: the directory in which the environment for CGIs is built, and a directory from which other server plug-ins might use them. 58 BT38-MPKI6-CVM-V1.0

65 Chapter 7 VeriSign Certificate Parsing Module (CPM) Table 7-1 provides the names of the fields, their location in the CGI environment, and their location in the server plug-in environment. Note These notes refer to Table 7-1: There can be zero or more organizational unit (OU) fields in a certificate. The HTTP_VSCERT_OUCOUNT environment variable returns the number of OU fields to CGI programs. The VSCERT_OUCOUNT environment variable returns the number of OU fields to server plug-ins. If HTTP_VSCERT_OUCOUNT is equal to n, then CPM creates HTTP_VSCERT_OU1 through HTTP_VSCERT_OUn. If there are no OU fields in the certificate, CPM does not create any HTTP_VSCERT_OU variables, and HTTP_VSCERT_OUCOUNT is set to zero Table 7-1 Variable Names for Certificate Field Names Certificate Field CGI Environment Variable Name Server Plug-in Variable Name Description Name HTTP_VSCERT_CN VSCERT_CN Subject Common Name HTTP_VSCERT_ VSCERT_ Subject address Address HTTP_VSCERT_ADDRESS VSCERT_ ADDRESS Subject street address Title HTTP_VSCERT_TITLE VSCERT_TITLE Subject s professional title Unique ID HTTP_VSCERT_UNIQUE VSCERT_UNIQUE Identifier unique to this certificate (typically the certificate serial number). BT38-MPKI6-CVM-V1.0 59

66 Managed PKI Certificate Validation and Parsing Guide Table 7-1 Variable Names for Certificate Field Names (Continued) Certificate Field CGI Environment Variable Name Server Plug-in Variable Name Description Organizati on HTTP_VSCERT_ORGANIZATION VSCERT_ORGANIZATI ON Subject s Organization (typically the name of the enterprise or government agency). Organizati on Unit Count Organizati on Unit HTTP_VSCERT_OUCOUNT VSCERT_OUCOUNT Number of OUs in the Subject certificate HTTP_VSCERT_OUn VSCERT_OUn Subject Organization Unit (OU) fields. The number of these fields is specified by the Subject Organization Unit Count field. Country HTTP_VSCERT_ISSUER_COUNTRY VSCERT_ISSUER_CO UNTRY Locality HTTP_VSCERT_ISSUER_LOCALITY VSCERT_ISSUER_LOC ALITY Issuer Country Issuer Locality CN HTTP_VSCERT_ISSUER_CN VSCERT_ISSUER_CN Issuer Common Name Organizati on HTTP_VSCERT_ISSUER_ORGANIZATION VSCERT_ISSUER_OR GANIZATION Issuer s Organization Organizati on Unit Count HTTP_VSCERT_ISSUER_OUCOUNT VSCERT_ISSUER_OU COUNT Number of OUs in the Issuer s CA certificate. 60 BT38-MPKI6-CVM-V1.0

67 Chapter 7 VeriSign Certificate Parsing Module (CPM) Table 7-1 Variable Names for Certificate Field Names (Continued) Certificate Field CGI Environment Variable Name Server Plug-in Variable Name Description Organizati on Unit HTTP_VSCERT_ISSUER_OUn VSCERT_ISSUER_OUn Organization Unit (OU) fields in the Issuer s CA certificate. The number of these fields is specified by the Issuer Organization Unit Count field. Not Before HTTP_VSCERT_ISSUER_NOTBEFORE VSCERT_ISSUER_NO TBEFORE Not After HTTP_VSCERT_ISSUER_NOTAFTER VSCERT_ISSUER_NO TAFTER Key Usage HTTP_VSCERT_EX_KEYUSAGE VSCERT_EX_KEYUSA GE Beginning of certificate validity period. End of certificate validity period. Comma separated string of all the key usage Extended Key Usage HTTP_VSCERT_EX_EKU VSCERT_EX_EKU Comma separated string of all the extended key usage DirectoryN ame Count under Subject AltName HTTP_VSCERT_EX_SAN_DIRNAMECOU NT VSCERT_EX_SAN_DIR NAMECOUNT Number of DirectoryNames under Subject AltName DirectoryN ame under Subject AltName HTTP_VSCERT_EX_SAN_DIRNAMEn VSCERT_EX_SAN_DIR NAMEn Directory Names under SubjectAltName. The number of these fields is specified by the DirectoryName Count under Subject AltName BT38-MPKI6-CVM-V1.0 61

68 Managed PKI Certificate Validation and Parsing Guide Table 7-1 Variable Names for Certificate Field Names (Continued) Certificate Field CGI Environment Variable Name Server Plug-in Variable Name Description DirectoryN ame Count under RFC822 HTTP_VSCERT_EX_SAN_RFC822COUNT VSCERT_EX_SAN_RF C822COUNT Number of DirectoryNames crlissuer DirectoryN ame Count under RFC822 HTTP_ VSCERT_EX_SAN_RFC822n VSCERT_EX_SAN_RF C822n Number of DirectoryNames crlissuer DirectoryN ame Count FullName HTTP_ VSCERT_EX_SAN_DNSNAMECOUNT VSCERT_EX_SAN_DN SNAMECOUNT Number of DirectoryNames crlissuer DirectoryN ame Count FullName HTTP_ VSCERT_EX_SAN_DNSNAMEn VSCERT_EX_SAN_DN SNAMEn Number of DirectoryNames crlissuer DirectoryN ame Count FullName HTTP_ VSCERT_EX_SAN_URICOUNT VSCERT_EX_SAN_URI COUNT Number of DirectoryNames crlissuer DirectoryN ame Count FullName HTTP_VSCERT_EX_SAN_URIn VSCERT_EX_SAN_URI n Number of DirectoryNames crlissuer DirectoryN ame Count under Universal Principle Name HTTP_VSCERT_EX_SAN_UPNCOUNT VSCERT_EX_SAN_UP NCOUNT Number of DirectoryNames crlissuer 62 BT38-MPKI6-CVM-V1.0

69 Chapter 7 VeriSign Certificate Parsing Module (CPM) Table 7-1 Variable Names for Certificate Field Names (Continued) Certificate Field CGI Environment Variable Name Server Plug-in Variable Name Description DirectoryN ame Count under Universal Principle Name HTTP_ VSCERT_EX_SAN_UPNn VSCERT_EX_SAN_UP Nn Number of DirectoryNames crlissuer DirectoryN ame Count FullName HTTP_ VSCERT_EX_SAN_GUIDCOUNT VSCERT_EX_SAN_GUI DCOUNT Number of DirectoryNames crlissuer DirectoryN ame Count FullName HTTP_ VSCERT_EX_SAN_GUIDn VSCERT_EX_SAN_GUI Dn Number of DirectoryNames crlissuer DirectoryN ame Count FullName HTTP_ VSCERT_EX_CDP_DPN_DIRNAMECOUN T VSCERT_EX_CDP_DP N_DIRNAMECOUNT Number of DirectoryNames FullName DirectoryN ame under CDP FullName HTTP_ VSCERT_EX_CDP_DPN_DIRNAMEn VSCERT_EX_CDP_DP N_DIRNAMEn Directory Names FullName. The number of these fields is specified by the DirectoryName Count under CDP FullName DirectoryN ame Count FullName HTTP_ VSCERT_EX_CDP_DPN_RFC822COUNT VSCERT_EX_CDP_DP N_RFC822COUNT Number of DirectoryNames crlissuer DirectoryN ame Count FullName HTTP_ VSCERT_EX_CDP_DPN_RFC822n VSCERT_EX_CDP_DP N_RFC822n Number of DirectoryNames crlissuer BT38-MPKI6-CVM-V1.0 63

70 Managed PKI Certificate Validation and Parsing Guide Table 7-1 Variable Names for Certificate Field Names (Continued) Certificate Field CGI Environment Variable Name Server Plug-in Variable Name Description DirectoryN ame Count FullName HTTP_ VSCERT_EX_CDP_DPN_DNSNAMECOU NT VSCERT_EX_CDP_DP N_DNSNAMECOUNT Number of DirectoryNames crlissuer DirectoryN ame Count FullName HTTP_ VSCERT_EX_CDP_DPN_DNSNAMEn VSCERT_EX_CDP_DP N_DNSNAMEn Number of DirectoryNames crlissuer DirectoryN ame Count FullName HTTP_ VSCERT_EX_CDP_DPN_URICOUNT VSCERT_EX_CDP_DP N_URICOUNT Number of DirectoryNames crlissuer DirectoryN ame Count FullName HTTP_ VSCERT_EX_CDP_DPN_URIn VSCERT_EX_CDP_DP N_URIn Number of DirectoryNames crlissuer DirectoryN ame Count FullName HTTP_ VSCERT_EX_CDP_DPN_UPNCOUNT VSCERT_EX_CDP_DP N_UPNCOUNT Number of DirectoryNames crlissuer DirectoryN ame Count under Universal Principle Name HTTP_ VSCERT_EX_CDP_DPN_UPNn VSCERT_EX_CDP_DP N_UPNn Number of DirectoryNames crlissuer DirectoryN ame Count FullName HTTP_ VSCERT_EX_CDP_DPN_GUIDCOUNT VSCERT_EX_CDP_DP N_GUIDCOUNT Number of DirectoryNames crlissuer 64 BT38-MPKI6-CVM-V1.0

71 Chapter 7 VeriSign Certificate Parsing Module (CPM) Table 7-1 Variable Names for Certificate Field Names (Continued) Certificate Field CGI Environment Variable Name Server Plug-in Variable Name Description DirectoryN ame Count FullName HTTP_ VSCERT_EX_CDP_DPN_GUIDn VSCERT_EX_CDP_DP N_GUIDn Number of DirectoryNames crlissuer DirectoryN ame Count crlissuer HTTP_ VSCERT_EX_CDP_CRL_DIRNAMECOUN T VSCERT_EX_CDP_CR L_DIRNAMECOUNT Number of DirectoryNames crlissuer DirectoryN ame under CDP crlissuer HTTP_ VSCERT_EX_CDP_CRL_DIRNAMEn VSCERT_EX_CDP_CR L_DIRNAMEn Directory Names FullName. The number of these fields is specified by the DirectoryName Count under CDP crlissuer DirectoryN ame Count FullName HTTP_VSCERT_EX_CDP_CRL_RFC822C OUNT VSCERT_EX_CDP_CR L_RFC822COUNT Number of DirectoryNames crlissuer DirectoryN ame Count under RFC822 HTTP_ VSCERT_EX_CDP_CRL_RFC822n VSCERT_EX_CDP_CR L_RFC822n Number of DirectoryNames crlissuer DirectoryN ame Count under CRL HTTP_ VSCERT_EX_CDP_CRL_DNSNAMECOU NT VSCERT_EX_CDP_CR L_DNSNAMECOUNT Number of DirectoryNames crlissuer DirectoryN ame Count FullName HTTP_ VSCERT_EX_CDP_CRL_DNSNAMEn VSCERT_EX_CDP_CR L_DNSNAMEn Number of DirectoryNames crlissuer DirectoryN ame Count FullName HTTP_ VSCERT_EX_CDP_CRL_URICOUNT VSCERT_EX_CDP_CR L_URICOUNT Number of DirectoryNames crlissuer BT38-MPKI6-CVM-V1.0 65

72 Managed PKI Certificate Validation and Parsing Guide Table 7-1 Variable Names for Certificate Field Names (Continued) Certificate Field CGI Environment Variable Name Server Plug-in Variable Name Description DirectoryN ame Count FullName HTTP_ VSCERT_EX_CDP_CRL_URIn VSCERT_EX_CDP_CR L_URIn Number of DirectoryNames crlissuer DirectoryN ame Count under Universal Principle Name HTTP_ VSCERT_EX_CDP_CRL_UPNCOUNT VSCERT_EX_CDP_CR L_UPNCOUNT Number of DirectoryNames crlissuer DirectoryN ame Count under Universal Principle Name HTTP_ VSCERT_EX_CDP_CRL_UPNn VSCERT_EX_CDP_CR L_UPNn Number of DirectoryNames crlissuer DirectoryN ame Count FullName HTTP_ VSCERT_EX_CDP_CRL_GUIDCOUNT VSCERT_EX_CDP_CR L_GUIDCOUNT Number of DirectoryNames crlissuer DirectoryN ame Count FullName HTTP_ VSCERT_EX_CDP_CRL_GUIDn VSCERT_EX_CDP_CR L_GUIDn Number of DirectoryNames crlissuer Table 7-2 lists the CPM Server Plug-in Commands for retrieving the value of the Name using a CGI: Table 7-2 CPM Server Plug-in Commands Language Perl C or C++ Command $ENV{'HTTP_VSCERT_CN'} getenv ( HTTP_VSCERT_CN ); 66 BT38-MPKI6-CVM-V1.0

73 Chapter 7 VeriSign Certificate Parsing Module (CPM) Using the Programmer s Library The programmer s library exports an application programmer s interface (API). This API is defined using ANSI C prototypes in the header file (cdr.h) provided with CPM. The header file provides a complete definition of the API. VeriSign provides C programming examples in cdrmain.c. Certificate Parsing API Use the CPM APIs to extract fields from client certificates using your custom program. Supported Platforms The API toolkit is available as a C/C++ library on Windows and 2000, Solaris, HP-UX. Programs using this API should link to one of the following shared libraries based on the platform, such as Solaris, HP-UX, or Windows. Operation libcdr.so or libcdr.sl or cdr.dll (The Certificate Parsing Module library) All of the functions take a base 64 encoded DER certificate in the form of a null-terminated string as their last parameter. The output strings (for example, char **commonnamestring) should be passed in as the address of a (char *), not a (char **); Since organizationunitstrings outputs an array of strings, it should be passed in as the address of a char **. After calling any of the functions, you free the memory which is allocated by the function-set of the API by calling the CDR_Free function: CDR_Free frees the memory that is allocated by the API. Syntax: void CDR_Free (char *pointer) Parameters: pointer: This is the pointer to the data that is to be freed. BT38-MPKI6-CVM-V1.0 67

74 Managed PKI Certificate Validation and Parsing Guide Return Values: None CPM API Function Descriptions int GetCommonNameStringAlloc Description This function gets the subject common name. Syntax int GetCommonNameStringAlloc (char **commonnamestring, char *b64certder) Parameters b64certder: The base 64-encoded cert DER. Output Parameters commonnamestring: The subject common name. Return Values: 0: On successful initialization. error-code: On error, refer to error codes in Table 7-3 on page 73. int Get AddressStringAlloc Description This function gets the subject address. Syntax int Get AddressStringAlloc (char ** addressstring, char *b64certder) Parameters b64certder: The base 64-encoded cert DER. Output Parameters addressstring: The subject s address. 68 BT38-MPKI6-CVM-V1.0

75 Chapter 7 VeriSign Certificate Parsing Module (CPM) Return Values: 0: On successful initialization error-code: On error, refer to error codes in Table 7-3 on page 73. int GetAddressStringAlloc Description This function gets the subject street address. Syntax int GetAddressStringAlloc (char **addressstring, char *b64certder) Parameters b64certder: The base 64-encoded cert DER. Output Parameters addressstring: The subject s street address. Return Values: 0: On successful initialization error-code: On error, refer to error codes in Table 7-3 on page 73. int GetUniqueIDStringAlloc Description This function gets the unique identifier of the certificate (typically the certificate serial number). Syntax int GetUniqueIDStringAlloc (char **uniqueidstring, char *b64certder) Parameters b64certder: The base 64 encoded cert DER. Output Parameters uniqueidstring: The unique identifier of the certificate. BT38-MPKI6-CVM-V1.0 69

76 Managed PKI Certificate Validation and Parsing Guide Return Values: 0: On successful initialization error-code: On error, refer to error codes in Table 7-3 on page 73. int GetOrganizationUnitStringsAlloc Description This function gets the subject Organization Unit (OU) fields. Syntax int GetOrganizationUnitStringsAlloc (char ***oustrings,char *b64certder) Parameters b64certder: The base 64 encoded cert DER. Output Parameters oustrings: The array of Organization Units. Return Values: 0: On successful initialization error-code: On error, refer to error codes in Table 7-3 on page 73. int GetOrganizationString Description This function gets the subject s Organization (typically the name of the enterprise or government agency). Syntax int GetOrganizationString (char **organizationstring, char *b64certder) Parameters b64certder: The base 64 encoded cert DER. Output Parameters organizationstring: This is the organization string. 70 BT38-MPKI6-CVM-V1.0

77 Chapter 7 VeriSign Certificate Parsing Module (CPM) Return Values: 0: On successful initialization error-code: On error, refer to error codes in Table 7-3 on page 73. int GetAllFieldsAlloc Description This function gets all fields listed in the following syntax. Syntax int GetAllFieldsAlloc (char ** addressstring, char **commonnamestring, char **uniqueidstring, char **addressstring, char ***oustrings, int *oucount, char *b64certder) Parameters b64certder: The base 64 encoded cert DER. Output Parameters addressstring: The subject s address. commonnamestring: The subject s common name. uniqueidstring: The unique identifier of the certificate. addressstring: The subject s street address. oustrings: The array of Organization Units. oucount: The count of Organization Units. Return Values: 0: On successful initialization error-code: On error, refer to error codes in Table 7-3 on page 73. int VSGetAllFieldsAlloc Description This function gets all of the VeriSign fields in the following syntax. Syntax int VSGetAllFieldsAlloc ( char ** address, char **commonname, char **title, char **uniqueid, char **address, BT38-MPKI6-CVM-V1.0 71

78 Managed PKI Certificate Validation and Parsing Guide char **organization, char ***organizationunits, int *orgunitcount, char **issuerorganization, char **issuerlocality, char **issuercountry, char **issuercommonname, char ***issuerorganizationunits, int *issuerorgunitcount, char **notbefore, char **notafter, VSCertV3Extensions_MV *v3extenstions, char *b64certder); Parameters b64certder: The base 64 encoded cert DER. Output Parameters address: The subject address. commonname: The subject common name. title: The title of the certificate. uniqueid: The unique identifier of the certificate. address: The subject street address. organization: The subject s organization. organizationunits: The subject s organization unit fields. orgunitcount: Number of subject organization units in the certificate. issuerorganization: The issuer s organization. issuerlocality: The issuer s locality. issuercountry: The issuer s country. issuercommonname: The issuer s common name. issuerorganizationunits: The issuer s organization unit fields. issuerorgunitcount: Number of organization units in the CA certificate. notbefore: The beginning of certificate validity period. notafter: The end of certificate validity period. v3extenstions: The structure which contains the values for V3 extensions. The structure is defined in the. 72 BT38-MPKI6-CVM-V1.0

79 Chapter 7 VeriSign Certificate Parsing Module (CPM) Return Values: 0: On successful initialization error-code: On error, refer to error codes in Table 7-3 on page 73. Certificate Parsing Module API Error Codes Table 7-3 describes the CPM API error codes. Table 7-3 CPM API error codes Error Codes Value Meaning CDRE_DER 0x1 Error in parsing the DER certificate. CDRE_ISSUER_FORMAT 0x2 Issuer format not recognized. CDRE_ALLOC 0x3 Memory allocation failed. CDRE_BAD_B64 0x4 Base 64 decoding failed. OSS_ERROR 0x06 OSS decoding error. EXTENSIONS_NOTPRESENT 0X07 No extensions present. BT38-MPKI6-CVM-V1.0 73

80 Managed PKI Certificate Validation and Parsing Guide 74 BT38-MPKI6-CVM-V1.0

81 re t pahc CHAPTER 8 8Online Certificate Status Protocol (OCSP) Background BT s Online Certificate Status Protocol (OCSP) services enable users and applications to determine the status (valid, revoked, suspended, expired, or unknown) of a particular certificate in real time. In practice, an end-user application implements an OCSP client (such as the VeriSign Certificate Validation Module CVM Web server plug-in) that issues a status request to an OCSP responder at BT Trust Services when an end-user certificate is presented for access to a secure Web resource. The client suspends acceptance of the certificate until the responder sends a response (digitally signed by BT) indicating the certificate s status. OCSP determines only the status of the certificate. The application program is responsible for verifying that the end user represented by the certificate has proper authorization to access the resource. As a security measure, all digital certificates have a limited lifetime (the operational period), typically one year. When the operational period passes, the certificate expires and becomes invalid. The owner of an invalid certificate should no longer use the certificate, and the certificate is no longer considered trustworthy. There are other situations in which a certificate should become invalid. For example, when a user terminates his or her employment, or there has been a loss or compromise of the private key, the certificate administrator or the user must request that BT Trust Services revoke the certificate. Revocation invalidates a certificate by permanently ending the operational period. When you request revocation of a certificate, or when the certificate expires, BT promptly revokes the BT38-MPKI6-CVM-V1.0 75

82 Managed PKI Certificate Validation and Parsing Guide certificate and updates its certificate Repository to indicate that the certificate is invalid. Another form of invalidation (available only to the OCSP service), certificate suspension, is essentially a temporary revocation. A suspended certificate appears as a revoked certificate to an OCSP request, and does not appear in a CRL. Unlike a revoked certificate, a suspended certificate can be returned to valid status. The intent of invalidating a certificate is to ensure that, when an invalid certificate is used to sign or encrypt a message, all recipients can be made aware that the certificate was revoked, and can thus no longer be trusted. To be able to alert a user that a particular certificate is invalid, application programs must be provided a mechanism for determining validity status. The process of determining status is also referred to as revocation checking. Contrasting OCSP and CRL Services Because BT s OCSP Services provide real-time, on-demand responses for particular certificates, OCSP presents some advantages over CRL services. These factors might enable a developer to create a simpler OCSP client application than an equivalent application using CRLs. BT s OCSP Services present the following advantages: There is no need to store CRLs. Over time, CRLs become larger. (BT mitigates this issue by providing partial CRLs that include only some revocation information.) An application that encounters certificates from multiple CAs must store at least one CRL for each CA. OCSP can be configured to log all OCSP transactions and provide a report of these transactions to the certificate administrator. OCSP services enable the certificate administrator to suspend a certificate as an alternative to revocation. A suspended certificate appears as a revoked certificate to an OCSP request, and does not appear in a CRL. Unlike a revoked certificate, a suspended certificate can be returned to valid status. Note Because OCSP services are real-time, their use requires an Internet connection. 76 BT38-MPKI6-CVM-V1.0

83 Chapter 8 Online Certificate Status Protocol (OCSP) How OCSP Services Works with CVM In the following example, the OCSP client application running the CVM sends an OCSP request for certificate status to BT s OCSP responder whenever an end user requests access to protected Web sites or other resources. If the OCSP responder indicates that the certificate is valid, the application determines whether the user presenting the certificate is allowed access to the resource. If the response is revoked, suspended, expired or unknown, the application denies access to the resource. Figure 8-1 illustrates this process. Figure 8-1 OCSP process The following is a step-by-step description of the OCSP process. The steps match the steps in Figure A user presents a request to access a protected resource, or to perform a transaction with your OCSP client application running the Certificate Validation Module (CVM). The request can be signed with the private key corresponding to the user s certificate. 2 The OCSP client verifies that the certificate chain and signature are correct. BT38-MPKI6-CVM-V1.0 77

84 Managed PKI Certificate Validation and Parsing Guide 3 The OCSP client then composes and sends an OCSP request to BT s OCSP responder. 4 The OCSP responder obtains the certificate status in real time from BT s certificate status database. 5 The OCSP responder generates an OCSP response that states the certificate status, digitally signs the response, and sends it to the OCSP client. 6 The OCSP client (running the CVM) verifies the signature of the OCSP responder to determine that the response is legitimate. 7 If the response states that the certificate is valid, the OCSP client application verifies that the user is authorized for access to the resource. If authorized, the OCSP client grants the user access to the requested resource. Note OCSP verifies only the status (valid, revoked, suspended, expired, or unknown) of a certificate presented. The Web site or network resource must still verify that the certificate provides the proper authorization for the end user to access the resource. If the response is revoked, unknown, expired, or suspended, the OCSP client denies access and displays the appropriate message: If the OCSP response states that the certificate is revoked, the CVM displays the default message of Certificate Revoked. If the OCSP response is unknown, the CVM displays the default message Server Error: Revocation Unknown. If the OCSP response states the certificate is expired, the CVM displays the default message Certificate Expired. If the OCSP responder certificate is expired, the CVM displays the same error message and write this to the log file. If the OCSP response returns any other non-valid status, the CVM displays the default message Server Error: Certificate Failed. The CVM writes additional information about this error to the log file. 78 BT38-MPKI6-CVM-V1.0

85 Chapter 8 Online Certificate Status Protocol (OCSP) Enabling the CVM for OCSP Service You configure how CVM accepts or rejects OCSP responses; implicitly or explicitly. With implicit trust, you set CVM to trust the CA that issued the OCSP responder certificate. CVM will trust any OCSP response signed by any certificate issued by that CA. With explicit trust, you set CVM to trust the specific OCSP responder certificate that signed the response. Explicit trust ensures that CVM only accepts OCSP responses signed by a certificate you set as trusted. Note BT recommends that you set explicit trust for greater security. You must obtain an OCSP responder certificate and configure the CVM for OCSP service to enable the CVM to work with BT s OCSP service. Follow these steps: Step 1 Obtain an OCSP responder certificate The OCSP responder uses a responder certificate to digitally sign the OCSP responses returned to the CVM. The CVM is configured to trust the responses signed by this certificate. Obtain and load the OCSP responder certificate by completing the following procedures: 1 On the Certificate Management page of the Managed PKI Control Center, click the Configuration button. 2 Click the Download OCSP certificate link to show the Download OCSP Responder Certificate page. 3 Click the Click here link to download the OCSP responder certificate. 4 Save the resulting certificate file as responder.crt. Step 2 Configure the CVM for OCSP service Follow these steps to configure the CVM for OCSP service. Note HTTPS is not supported for these OCSP clients. BT38-MPKI6-CVM-V1.0 79

86 Managed PKI Certificate Validation and Parsing Guide 1 Add the URL for the OCSP service to the CVM: Microsoft Internet Information Server: Add the URL for the OCSP service to the CVM by specifying the following in the OcspUrl input field of valconfig.exe. Netscape/iPlanet Enterprise Server: Add the URL for the OCSP service to the CVM by adding the following value to the obj.conf file: ocsp-url=" Stronghold Secure Web Server: Add the URL for the OCSP service to the CVM by adding the following value to the httpd.conf file: VSVAL_SetOpt ocsp-url " 2 If the Web server on which the CVM is installed does not have a direct route available to the OCSP responder, you may need to configure the http-proxy option. If a proxy is specified, it is used for outgoing OCSP requests. Configure this option when you use valconfig.exe to configure the CVM parameters. 3 Set up implicit or explicit trust: Add the certificate and chain to be trusted to the val_config.txt configuration file. This chain should terminate in a self-signed root certificate (which is also required in the configuration file). This chain is typically two certificates deep; the OCSP signer certificate is issued by a self-signed root. Each certificate should have a separate entry in val_config.txt. To enable implicit trust, add the certificate that issued the OCSP responder certificate and all other certificates in the chain (to enable implicit trust). To enable explicit trust, also add the OCSP responder certificate. Example additions to val_config.txt: # PCA1 ROOT, uses file-prefix ENTRY=CERT FILE DER ROOT READ=pca1ss.509 # OCSP Responder certificate 80 BT38-MPKI6-CVM-V1.0

87 Chapter 8 Online Certificate Status Protocol (OCSP) ENTRY=CERT FILE DER READ=Responder.crt Note When the OCSP responder certificate expires, you must renew the certificate and replace it in the val_config.txt configuration file. BT38-MPKI6-CVM-V1.0 81

88 Managed PKI Certificate Validation and Parsing Guide 82 BT38-MPKI6-CVM-V1.0

89 xi nd pe Ap APPENDIX A ACVM Configuration Values This appendix contains the values of Init.fn for configuring the CVM with obj.conf, valconfig.exe, or httpd.conf. Some parameters are used by Microsoft IIS only; such parameters are noted in the Description column of Table A-1). For iplanet Server (on Windows or UNIX), use forward slashes (/). For Stronghold (on UNIX) use forward slashes (/). For IIS (on Windows) use backslashes (\). Table A-1 Arguments to Init fn for configuring plug-in with obj.conf or valconfig.exe or httpd.conf Parameter Description Sample Value cfg-filename file-prefix url-prefix CRL status checking only ocsp-url OCSP status checking only Required The configuration file that the CVM should read Required. The directory containing certificates and CRLs The URL prefix to be prepended to URL locations The URL CVM uses to access BT s OCSP responder For Windows: C:\VeriSign\cvm\config\val_co nfig.txt For UNIX: /VeriSign/cvm/config/val_confi g.txt For Windows: C:\VeriSign\cvm\certcache For UNIX: /VeriSign/cvm/certcache See Appendix B, Downloading Certificate Revocation Lists, for value. BT38-MPKI6-CVM-V1.0 83

90 Managed PKI Certificate Validation and Parsing Guide Table A-1 Arguments to Init fn for configuring plug-in with obj.conf or valconfig.exe or httpd.conf (Continued) Parameter Description Sample Value cache-dir log-security log-info default-ldap Required. The local directory in which downloaded certificates and CRLs are stored. cache-dir must be an existing directory. The CVM does not create the directory if it does not exist. The Web server must have write access to this directory. If there is a problem with this directory, the CVM attempts to use a system-wide temp directory. Should access denials be logged by the server plug-in? Should info messages be logged by the server plug-in? The default LDAP server, containing certificates and CRLs. default-ldap specifies the name of an LDAP server that contains certificates and CRLs. If a CRL is required to verify a client certificate, and the configuration file does not specify the location of that CRL, an LDAP query is sent to this server. If default-ldap is unspecified, the plug-in looks up the CRL directly from BT. If you wish to disable this behavior, set default-ldap="". Note: The plug-in may not query the LDAP server if the configuration file specifies locations for some, but not all, of the required certificates or CRLs. If your system is behind a firewall, see the description of ldap-http-proxy. Enter the correct directory. For example: For NT: C:\VeriSign\cvm\certcache\ For UNIX: /VeriSign/cvm/certcache on or off, as appropriate. on or off, as appropriate. Enter the correct directory. For example: directory.trustwise.com 84 BT38-MPKI6-CVM-V1.0

91 Appendix A CVM Configuration Values Table A-1 Arguments to Init fn for configuring plug-in with obj.conf or valconfig.exe or httpd.conf (Continued) Parameter Description Sample Value update-hours no-check-chain Frequency of CRL updates (in hours). update-hours provides a method for automatically reacquiring CRLs even if they have not yet expired. Each time the plug-in checks a certificate, it gets the current time. If a CRL update has not occurred within the time period specified by update-hours, the plug-in refreshes all CRLs. For example, to automatically refresh CRLs every day, set update-hours="24". (If Premium Revocation is purchased, set update-hours="1"). If you do not want the plug-in to automatically refresh CRLs that have not yet expired, leave update-hours out of the obj.conf file, or leave the line empty in valconfig. Do not set update-hours to 0, as this causes the plug-in to reacquire CRLs for every transaction. no-check-chain applies only to CRL status checking. If set to on, only the CRL corresponding to the lowest CA in the hierarchy is searched; otherwise the CRL corresponding to each CA in the chain is searched. This setting also implies that only the CRL corresponding to the lowest CA in the hierarchy needs to be present in the trust configuration (val_config.txt) for the CVM to work. Set no-check-chain if there is no CRL available for the root certificate. This is useful if you operate a private CA. When no-check-chain is set, the certificate chain is followed until a valid root is found. However, only the CRL for the issuing CA is used when verifying the validity of the user certificate. The plug-in cannot revoke intermediate CAs when this option is used. Note: Setting no-check-chain= on applies to the CRL chain only. A valid CA certificate chain is always required to validate the signature on a CRL. Enter the number of hours. For example: 24 on (recommended for Managed PKI Private) off (highly recommended for Managed PKI Public- Do not use this parameter) BT38-MPKI6-CVM-V1.0 85

92 Managed PKI Certificate Validation and Parsing Guide Table A-1 Arguments to Init fn for configuring plug-in with obj.conf or valconfig.exe or httpd.conf (Continued) Parameter Description Sample Value error-cgi http-proxy (Optional) The name of the CGI program to run when access is denied. error-cgi specifies a customized error page that is displayed whenever access to your Web site is denied. If the default page is adequate, leave error-cgi out of the obj.conf file or leave the line empty in valconfig.exe. error-cgi redirects users with revoked certificates to a non-ssl enrollment page. certstatus.csh and certstatus.pl show examples of error-cgi use. For example, if error-cgi is set to tatus.csh, the CGI script certstatus.csh is called when a certificate problem prevents access to the Web site. Ensure that the value begins with " or " or the plug-in considers it a local file. The plug-in passes the certificate status code in the query string (such as Note: Ensure that the error-cgi value is not one of the protected URLs. (Optional) The name of the HTTP proxy server used to access the Internet. http-proxy specifies an HTTP proxy server through which to connect to the Internet. If you are not using a proxy, leave http-proxy out of the obj.conf file or leave the line empty in valconfig. When the plug-in retrieves HTTP URLs, it routes its requests through this server. If the proxy server is running on a port other than the default (80), you can specify that port by adding ":port" after the server name. Enter the appropriate path to the CGI error program. For example: m/cgi-bin/certstatus.csh Enter the appropriate server name and port value. For example: proxy or proxy:85 86 BT38-MPKI6-CVM-V1.0

93 Appendix A CVM Configuration Values Table A-1 Arguments to Init fn for configuring plug-in with obj.conf or valconfig.exe or httpd.conf (Continued) Parameter Description Sample Value ldap-http-proxy log-file-name protected-dirs isa-install (Optional) Specifies an HTTP server that will proxy LDAP lookups. This can be used to automatically acquire CRLs from an LDAP directory when behind a firewall. If you are not using a proxy, leave ldap-http-proxy out of the obj.conf file or leave the line empty in valconfig. You can use ldap-http-proxy in conjunction with http-proxy to access an LDAP proxy server on the Internet. If the proxy server is running on a port other than the default (80), you can specify that port by adding ":port" after the server name. (IIS only.) The name of the log file to which the plug-in should write. This is the Microsoft IIS plug-in s buffered log file for informational and security messages. While the server is running, results may not appear in the log for a long time. You must stop the Web publishing service to flush the contents of the file to the disk file. (IIS only.) Specifies the URL prefixes to be protected with CVM. You can specify as many prefixes as you wish. Separate prefixes with semicolons. (IIS and ISA only) Specifies whether CVM is installed on ISA server. A value of 1 means CVM is installed on ISA server. The default value is 0. Enter the appropriate ldap server name and port value. For example: proxy or proxy:85 Enter the appropriate file name. For example: For Windows: C:\VeriSign\cvm\log\cvm.log For example: protected-dirs="/protected;/vs admin;/protected-cgi" Protecting a parent prefix automatically provides the same protection to the child prefix. For example, protecting /prefix1 also protects /prefix1/sub1 and /prefix1/sub1/sub2. BT38-MPKI6-CVM-V1.0 87

94 Managed PKI Certificate Validation and Parsing Guide 88 BT38-MPKI6-CVM-V1.0

95 xi nd pe Ap APPENDIX B BDownloading Certificate Revocation Lists In its role as a Certification Authority, BT publishes certificate revocation information in the form of Certificate Revocation Lists (CRL). BT regularly updates and makes available to the public its CRL for each CA. You have two options for downloading CRLs from BT: through the Managed PKI Control Center, or directly from a secure Web page. Downloading the CRL from the Managed PKI Control Center meets the needs of the majority of Managed PKI installations. However, if you use an application such as VeriSign s CVM to automatically download the CRL, you need to configure the application with the appropriate URL. This appendix lists the secure Web page URLs for Managed PKI Public and Managed PKI Private hierarchies. Procedures for configuring CVM with these URLs are provided in Chapter 3, Chapter 5, and Chapter 6. If you use a third-party application to download and check CRLs, refer to the documentation provided with that application for configuration procedures. Managed PKI Public If you have a Managed PKI Public hierarchy, use the following URLs to access the root and intermediate CA CRLs. Production System PCA2 root CA CRL (PKCS#7 format) BT38-MPKI6-CVM-V1.0 89