MPKI6 TechRef

Managed PKI
Technical Reference
CUSTOMER MANUAL
Customer Support: +44(0) 870 608 7878 support@trustwise.com BT38-MPKI6-TRF-V1.1
Managed PKI Technical Reference
Managed PKI Technical Reference BT38-MPKI6-TRF-V1.1 has been produced from: VeriSign Inc. Doc Ref 00010843 Copyright 1999 - 2003 VeriSign, Inc. All rights reserved. Printed in the United States of America. Publication date: August 2003 BT Revision date: October 2006 This document supports Managed PKI 6.0 and all subsequent releases unless otherwise indicated in a new edition or release notes. U.S. Patent 6,324,645 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-TRF-V1.1
Contents
Contents
Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
About This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Chapter 2 Understanding Local Hosting . . . . . . . . . . . . . . . . . . . . . . 5

Introduction to Local Hosting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Using the Digital ID Center Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Using Customizer Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Modifying Digital ID Center Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Modifying Digital ID Center Pages After the Customizer Has Placed Them Into Your Web Server Directory . . . . . . . . . . . . . . . . . . . . . . . 10 Making Subsequent Modifications to Your Digital ID Center Pages . . . . 11
Chapter 3 Understanding Passcode Authentication . . . . . . . . . 15

About Passcode Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Acquiring a Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Fulfilling Managed PKI Administrator Responsibilities . . . . . . . . . . . . . . . . 18 Managing Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Implementing and Administering Passcode Authentication . . . . . . . . . . 19
Chapter 4 Understanding the Automated Administration Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Understanding the Components of Automated Administration . . . . . . . . . . 28 Protecting Sensitive Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Operational Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Native Character Support for Automated Administration . . . . . . . . . . . . . . 33
Chapter 5 Understanding Subscriber Certificate Renewal . . . 35

Renewal Methods for Automated Administration Implementations . . . . . . 35 Using Automatic Renewal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Identifying Re-Used Certificate Fields . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Addressing Implementation Considerations . . . . . . . . . . . . . . . . . . . . . . 38 Using Re-Authentication Renewal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
BT38-MPKI6-TRF-V1.1 iii
Using Client Authentication Renewal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Addressing Implementation Considerations . . . . . . . . . . . . . . . . . . . . . . 39
Chapter 6 Understanding Signing Utilities . . . . . . . . . . . . . . . . . . . 41

Using the Software Signing Option swkeygen . . . . . . . . . . . . . . . . . . . . 41 Using the Hardware Signing Option aakeygen . . . . . . . . . . . . . . . . . . . . 42 Importing Certificates swimport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Chapter 7 Working with Automated Administration APIs . . . . 47

Understanding AA Flow Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Enrollment and Registration Flow of Control . . . . . . . . . . . . . . . . . . . . . . 49 Using the Automated Administration APIs . . . . . . . . . . . . . . . . . . . . . . . . . 50 Understanding Data Structures and Definitions . . . . . . . . . . . . . . . . . . . 50 Understanding VSAA_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Using the Verification and Registration API . . . . . . . . . . . . . . . . . . . . . . . . 52 Understanding ProcessEntries Operations . . . . . . . . . . . . . . . . . . . . . . . 53 Using the Signing API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Using Common name/value pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Understanding Additional Data Source Configuration . . . . . . . . . . . . . . . . . 67 VerifyUser( ) Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Using Custom Shared Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Using Name/Value Pairs for Enrolling End-Entity Certificates . . . . . . . . . . 73 Using regInfo Content Details for Personal Client Certificates . . . . . . . . 73 Using regInfo Content Details for IPSEC Certificates . . . . . . . . . . . . . . . 77 Preparing to Enroll for an RA Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Understanding regInfo Value Tag Definitions . . . . . . . . . . . . . . . . . . . . . . . 81
Chapter 8 CSR-Based Enrollment . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Chapter 9 Using an ODBC Data Source With Automated Administration or Key Management Service . . . . . . . . . . . . . . 85
Setting Up an ODBC Data Source on Unix . . . . . . . . . . . . . . . . . . . . . . . . . 85 Setting Up An ODBC Data Source on Windows . . . . . . . . . . . . . . . . . . . . . 87
iv
BT38-MPKI6-TRF-V1.1
Contents
Chapter 10 Using a Flat File for Verification Data . . . . . . . . . . . . 91

About validuser.txt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Understanding validuser.txt File Structure . . . . . . . . . . . . . . . . . . . . . . . . . 92 Understanding How validuser.txt Operates . . . . . . . . . . . . . . . . . . . . . . . . 92 Example Flat File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Chapter 11 Understanding Directory Technology (Overview) 95

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Understanding X.500 the ISO Standard Directory Architecture . . . . . . . 97 Understanding LDAP Internet Standard for Directory Access . . . . . . . . 99 Understanding the Schema How a Directory Represents Information . 99 Using Windows 2000 with Active Directory . . . . . . . . . . . . . . . . . . . . . . . 100 Using Active Directory Server Info . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Chapter 12 Implementing Native Character Encodings with AA or KMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Managed PKI Support for Native Character Encodings . . . . . . . . . . . . . . Same Encoding Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ASCII-Only Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 103 103 104
Chapter 13 Downloading Certificate Revocation Lists . . . . . . 105

Accessing CRLs Through Managed PKI Public . . . . . . . . . . . . . . . . . . . . 106 Downloading Production System CRLs . . . . . . . . . . . . . . . . . . . . . . . . 106 Downloading Pilot System CRLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Accessing CRLs Through Managed PKI Private . . . . . . . . . . . . . . . . . . . 106 Downloading Production System CRLs . . . . . . . . . . . . . . . . . . . . . . . . 107 Downloading Pilot System CRLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Chapter 14 Working With Sophialite . . . . . . . . . . . . . . . . . . . . . . . . 109

Understanding Sophialite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 Configuring Sophialite to use a Proxy Server . . . . . . . . . . . . . . . . . . . . . . 111 Understanding the Form Definition File (FDF) . . . . . . . . . . . . . . . . . . . . . Understanding Variable Definitions in the FDF . . . . . . . . . . . . . . . . . . . Formatting the Form Definition File . . . . . . . . . . . . . . . . . . . . . . . . . . . Avoiding Reserved Name Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . 111 116 121 122
Modifying End-User Error Message Text . . . . . . . . . . . . . . . . . . . . . . . . . 125

BT38-MPKI6-TRF-V1.1 v
Editing the haydn.edf File (an Example haydn.edf Code) . . . . . . . . . . . 126 Following Editing Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Designing Web Pages for Use With Sophialite . . . . . . . . . . . . . . . . . . . . . Using the form_file INPUT Element . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the html_file INPUT Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Additional INPUT Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using VHTML Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 126 127 127 128
Chapter 15 Understanding the Browser Emulation Specification

129 (Optional) Tools Used by the Client to Interface with Managed PKI . . . . . 129 Understanding Fundamental Assumptions . . . . . . . . . . . . . . . . . . . . . . . . 130 Understanding End Entity Token Generation . . . . . . . . . . . . . . . . . . . . . . 131 Working with HTTP and MIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 End Entity Certificate Request Process for Managed PKI . . . . . . . . . . . . Requesting a Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Response from Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Picking up the Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . End Entity Certificate Request Process for Managed PKI Key Management Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Requesting a Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Response from Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Pickup Certificate for digitalSignature Key . . . . . . . . . . . . . . . . . . . . . . Pick up keyEncipherment Key and its Certificate . . . . . . . . . . . . . . . . . Renew Certificate for digitalSignature key . . . . . . . . . . . . . . . . . . . . . . Renew keyEncipherment Key and its Certificate . . . . . . . . . . . . . . . . . 133 133 136 137 138 138 141 145 145 146 146
Appendix A About Certificate-Based Access Control . . . . . . . 149

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 Certificates as a Basis for Access Control . . . . . . . . . . . . . . . . . . . . . . . . Subscriber Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Designing a Certificate-Based Access Control System . . . . . . . . . . . . . Certificate Lifecycle for Subscriber Certificates in Browsers . . . . . . . . . Denial of Access and Revocation Checking . . . . . . . . . . . . . . . . . . . . . Access Control Architectural Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . Just Trust the Root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Map to User Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Map to User Accounts In LDAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Map to Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
vi
150 150 151 152 152 153 153 154 155 156
BT38-MPKI6-TRF-V1.1
Contents
Microsoft Examples: Internet Information Server (IIS) Solutions . . . . . . . Preparing IIS for Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Just Trust the Root (IIS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Map to User Accounts (IIS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Netscape Examples: Web Server Solutions . . . . . . . . . . . . . . . . . . . . . . . Installing a Server Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Just Trust the Root (Netscape) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Map to User Accounts In LDAP (Netscape) . . . . . . . . . . . . . . . . . . . . . Certmap.conf Configuration File for Managed PKI (Netscape) . . . . . .
156 157 162 163 176 176 176 179 182
Implementation Guidelines for Managed PKI Web Access Control . . . . . 188
Appendix B Characters Allowed in Digital Certificates . . . . . . 189

Characters Allowed on Administrator Pages . . . . . . . . . . . . . . . . . . . . . . 190 Characters Allowed on End-user Enrollment Pages . . . . . . . . . . . . . . . . . 191
Appendix C Understanding How BT Trust Services Generates Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 Appendix D Using Netscapes Directory Server with Managed PKI LDIF Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Using Managed PKI LDIF Files with Netscape iPlanet 4.x . . . . . . . . . . . . Installation and Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Create Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using your directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Netscape Communicator to send secure e-mail . . . . . . . . . . . . . 197 197 198 201 201 202
Importing Managed PKI LDIF Files into iPlanet Directory Server v5.0 . . . 204
Appendix E Adding Fields to the Subscriber Enrollment Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

Modifying the Subscriber Enrollment Pages . . . . . . . . . . . . . . . . . . . . . . . Modifying the HTML Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modifying FDF Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modifying enroll_wait.htm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 209 210 211
Predefined Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
BT38-MPKI6-TRF-V1.1
vii
Appendix F Removing Fields from the Certificate Enrollment Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 Removing a Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
viii
BT38-MPKI6-TRF-V1.1
CHAPTER 1
Introduction
1 ret pahC
VeriSign Managed PKI consist of a variety of tools and services to help you establish a customized public key infrastructure (PKI) and Certificate Authority (CA) system for issuing and managing digital certificates throughout your enterprise. This guide contains reference information to help you keep Managed PKI core technologies running smoothly. This chapter includes the following topics: About This Manual on page 1 Related Documents on page 3
About This Manual

This manual is intended for Managed PKI administrators and other key personnel who work with Managed PKI. Managed PKI Technical Reference contains basic information about how Managed PKI works and repeated tasks that the Managed PKI administrator might need to perform, as well as reference information for Automated Administration. One-time operations such as installation are described in a separate manual, Managed PKI Installation and Configuration. This manual is organized as follows: Chapter 2, Understanding Local Hosting, describes the operation of Local Hosting, and explains how to modify the Web pages seen by end users. Chapter 3, Understanding Passcode Authentication, describes the automated process of authenticating requests for certificates through Passcode Authentication.
BT38-MPKI6-TRF-V1.1
Chapter 4, Understanding the Automated Administration Feature, identifies the primary components involved in Automated Administration (AA) and describes the process in which a verification data source is used to automate the process of authenticating requests for certificates. Chapter 5, Understanding Subscriber Certificate Renewal, describes Automatic Renewal, Re-Authentication Renewal, and Client Authentication Renewal, which are the three options for processing subscriber certificate renewals with Automated Administration. Chapter 6, Understanding Signing Utilities, discusses the key generation (swkeygen and aakeygen) and certificate import (swimport) components for the Automated Administration signing options. Chapter 7, Working with Automated Administration APIs, describes Automated Administration application programmable interfaces (APIs), and explains how to use them to customize your verification and registration data sources. Chapter 7 also includes information on the regInfo name/value pairs needed to enroll for End-user certificates, IPSec certificates and Software Validation certificates. Chapter 8, CSR-Based Enrollment, describes the process of certificate enrollment and acquisition using a CSR. Chapter 9, Using an ODBC Data Source With Automated Administration or Key Management Service, describes the use of ODBC data sources. Chapter 10, Using a Flat File for Verification Data, explains how to use a text file for testing Automated Administration signing. Chapter 11, Understanding Directory Technology (Overview), explains the fundamental concepts underlying directory services, including introductory information about X.500 and LDAP. Chapter 12, Implementing Native Character Encodings with AA or KMS, describes how to enable end users to enter data in their preferred character set. Chapter 13, Downloading Certificate Revocation Lists, gives instructions for checking lists of certificates that are no longer valid. Chapter 14, Working With Sophialite, describes the programming interface to Sophialite, the CGI program that communicates data from subscribers browsers (viewing HTML pages hosted on your local Web server) to a BT
2 BT38-MPKI6-TRF-V1.1
Chapter 1 Introduction
Trust Services Web server. In addition, the chapter gives details about designing Web pages for use with Sophialite. Chapter 15, Understanding the Browser Emulation Specification, describes the emulation protocol between a PKI-enabled client and either a VeriSign Managed PKI RA or a VeriSign Managed PKI CA. Appendix A, About Certificate-Based Access Control, provides foundation knowledge about access control in general and certificate-based access control in particular. Appendix B, Characters Allowed in Digital Certificates, includes the list of ASCII characters allowed in certificate enrollment requests. Appendix C, Understanding How BT Trust Services Generates Certificates, is an overview of the information path from the initiation of a request through the processing center, and back to the originating browser. Appendix D, Using Netscapes Directory Server with Managed PKI LDIF Files, describes the use of LDAP directories with Managed PKI. Appendix E, Adding Fields to the Subscriber Enrollment Pages, describes customizing end-user pages. Appendix F, Removing Fields from the Certificate Enrollment Form, describes customizing end-user pages.
Related Documents
The following documents support information provided in this document. All Managed PKI customer documents are available on the Managed PKI CD or from the Control Center Download page. Managed PKI Introduction Managed PKI Installation and Configuration Managed PKI Administrators Handbook Authentication Services Hardware/Software Requirements Authentication Services Error Codes and Troubleshooting Guide Enterprise Support and Service Overview
BT38-MPKI6-TRF-V1.1
Key Management Service Administrators Handbook Key Management Service Installing Managed PKI with Key Management Service
BT38-MPKI6-TRF-V1.1
CHAPTER 2
Understanding Local Hosting

2 ret pahC
This chapter explains the Local Hosting feature of Managed PKI, and gives instructions for customizing the end-user Web pages. For instructions on installing Local Hosting, refer to Managed PKI Installation and Configuration or Key Management Service Installing Managed PKI with Key Management Service. This chapter includes the following topics: Introduction to Local Hosting on page 6 Using the Digital ID Center Pages on page 6 Using Customizer Commands on page 8 Modifying Digital ID Center Pages on page 10
BT38-MPKI6-TRF-V1.1
Introduction to Local Hosting

The Local Hosting feature enables your organization to host the end-user pages on your Web server.
Figure 2-1 Typical Local Hosting network configuration
When an end user enrolls for a certificate or performs other certificate management tasks, he or she works on the Digital ID Center Web pages that are locally hosted at your Web site. The Digital ID Center pages consist of entry forms that pass information from subscribers to BT Trust Services, and refreshed VHTML (Variable HTML) pages that return information from BT to subscribers. Local Hosting is required for such product features as Automated Administration and Key Management Service. Many customers use Local Hosting even when it is not required so they can customize the Digital ID Center pages.
Using the Digital ID Center Pages

Subscribers use Digital ID Center pages for the following activities: Requesting a certificate (filling out and submitting the certificate enrollment page)
BT38-MPKI6-TRF-V1.1
Chapter 2 Understanding Local Hosting
Retrieving a certificate when it is issued Finding another subscribers certificate Renewing their certificates Revoking their own certificates By implementing Local Hosting, your organization can customize the Digital ID Center pages on your Web server. Instead of a standard BT Trust Services Digital ID Center page with your companys name on top, your organization can provide your end users with a page that also contains your own text, links, and logo. For instance, you may: Provide special instructions for your subscribers Add links to other services on your site Modify the appearance and functionality to blend seamlessly with your organizations other intranet pages Although BT Trust Services continues to host all Control Center pages (the pages used to administer the Managed PKI service) and certificate management operations, you control the appearance and design of the end-user interface. Figure 2-2 and Figure 2-3 provide examples of customization. In Figure 2-2, the completion page includes the normal logo and several links. In Figure 2-3, the organizations logo replaces the normal logo, and the links have been removed.
Figure 2-2 Completion page before customization

BT38-MPKI6-TRF-V1.1 7
Figure 2-3 Completion page after customization
As an administrator, in addition to your certificate management responsibilities, you may be responsible for maintaining your companys Digital ID Center pages. You can modify the HTML files by following the procedures in this chapter.
Using Customizer Commands

The first time Managed PKI was configured with the Policy Wizard, the BT Trust Services installer or someone at your organization entered the Local Hosting Base URL (the URL for the Web server that hosts user enrollment pages at your organization) into the Policy Wizard. Each time the Policy Wizard is run, Managed PKI generates a Policy File based on the specifications entered. After the Managed PKI configuration is complete, the installer downloads a Policy File from BT, inserts the Managed PKI CD, and runs a customizer command. The customizer commands (so called because they generate customized pages based on your Policy Wizard specifications) reside on the Managed PKI CD in the sitekit/engine subdirectory of the directory that applies to your operating system. There are several customizer commands, depending upon which area requires customization. To find the customer command that applies to you, browse in the Managed PKI CD and go to the directory that indicates the operating system you use. Once in that directory, move to sitekit/engine to see the commands. The sitekit/engine directory contains the following commands, with the section in angle brackets indicating a variable that depends on the operating system directory in which the command resides:
BT38-MPKI6-TRF-V1.1
install-<nt|sun|hpux|aix> installs or modifies Local Hosting pages. This
command must be run every time you make changes to the Policy File. Details about the install command and customizing local hosting pages are found in Managed PKI Installation and Configuration or Key Management Service Installing Managed PKI with Key Management Service.
install-aa-<nt|sun|hpux|aix> customizes Automated Administration
software. Refer to Managed PKI Installation and Configuration for more information about this command.
install-kms-<nt|sun|hpux|aix> customizes Key Management Service software. Refer to Key Management Service Installing Managed PKI with Key Management Service for more information about this command. migrate-<nt|sun|hpux|aix> identifies Local Hosting pages that might be
overwritten during an upgrade. This command is needed only if you are upgrading from one version of Managed PKI to a different version. Refer to Managed PKI Upgrading for more information. The Digital ID Center pages produced during the first installation, although customized to your configuration, are standard BT Trust Services pages containing the organization name you entered when enrolling for your administrator certificate. If you want to further modify them by changing HTML or adding text or logos, you can open the HTML files in a text editor and make changes as described in Modifying Digital ID Center Pages on page 10. The Local Hosting installation produces two kinds of HTML pages: HTML pages that include entry forms which pass information from the user to BT Trust Services. Chapter 14, This section is intended for HTML authors using VHTML (Variable HTML) and Sophialite to:, provides detailed information on the named variables used in the Digital ID Center pages. Variable HTML (VHTML) pages that return information to the user. For example, VHTML pages may be used to display the information requested by a user. See Chapter 14, This section is intended for HTML authors using VHTML (Variable HTML) and Sophialite to:, for information about VHTML.
BT38-MPKI6-TRF-V1.1
Modifying Digital ID Center Pages

After the install customizer has been run for the first time and the HTML files are placed in the proper destination directory, you may want to make further modifications to change the standard Digital ID Center pages to pages that match your corporate look and feel, and that streamline your companys enrollment process.
Modifying Digital ID Center Pages After the Customizer Has Placed Them Into Your Web Server Directory
Once the original install command has been completed and the Digital ID Center pages are installed into your companys Web server, you may modify them to add text and logos specific to your company. To do this, use the commands shown in this section to place the pages in a temporary directory (staging directory) and edit and test them. Since the files in the staging area are not associated with a server, the forms do not post data. However, once you move the files into the working directory of your Managed PKI server, they work correctly. The examples here assume that the htmldocs directory resides in the recommended directory C:\VeriSign\OnSite\webroot. The staging directory may be named something like C:\VeriSign\TempDigitalIDCenter. The Policy File is ACMEBank.policy in this example.
1 2
Put the Managed PKI CD in the CD drive. On the UNIX or DOS command line, go to the CD drive, then to the directory that has the name that matches the operating system you are using. Still on the command line, run the customizer (install-<nt|sun|hpux|aix>) command using the following syntax:
install-<nt|hpux|sun|aix> <source dir> <dest dir> <policyfile>
Note
Type the entire path name for the source, destination, and Policy File.
source dir: C:\VeriSign\OnSite\webroot, the full path to the directory where the HTML files now reside.
10
BT38-MPKI6-TRF-V1.1
dest dir: The full path to the destination where you want to place the files, for example, C:\VeriSign\TempDigitalIDCenter. policyfile: The full path to the Policy File you downloaded after you ran the Policy Wizard, for example, C:\Policies\ACMEBank.policy This executed command places duplicates of your editable Digital ID Center pages into the destination directory called TempDigitalIDCenter.
4
Go to TempDigitalIDCenter and edit the HTML files to make your customizations. Follow these guidelines when editing Local Hosting pages: Use a text editor such as Notepad or vi, not a commercial HTML editor. Commercial HTML editors make unwanted changes to the pages. Do not alter any text that appears between the following tags:
<-- VSSKBEGIN <policy-name>#<frag-id> --> <-- VSSKEND <policy-name>#j<frag-id> -->
Each of these tags must appear alone on a text line. Modifying text that appears between VSSKBEGIN and VSSKEND tags causes the pages to malfunction.
CAUTION 5
After you make the changes, test the pages. When you have finished testing, move the files to the htmldocs directory in C:\VeriSign\OnSite\webroot.
Making Subsequent Modifications to Your Digital ID Center Pages

Any time your organization adds an option to or changes your Managed PKI configuration, or upgrades to another version of Managed PKI, you must reconfigure with the Policy Wizard, download a new Policy File, optionally run the migration utility to determine which pages will be overwritten during customization, and run the install customizer command again. Use the instructions in this section if you already have modified your Digital ID Center pages (as described in Modifying Digital ID Center Pages After the Customizer Has Placed Them Into Your Web Server Directory on page 10) and you want your pages to still look the same way after running the Policy Wizard. These instructions help you avoid overwriting your modified HTML pages with the standard Digital ID Center pages during the customization process.
You may be running the Policy Wizard because: You are changing your existing Managed PKI configuration. You are upgrading from a previous version to the current version of Managed PKI (See Managed PKI Upgrading) and must run the Policy Wizard to perform your initial configuration of the new version of Managed PKI. You need to run the customizer command without overwriting your existing Digital ID Center pages. In this case, your existing Digital ID Center pages, rather than the templates on the CD, serve as the basis for formatting. The command uses your existing files as the source files and places copies of them back into the destination directory. This enables you to preserve the changes you made to your existing HTML files when you change the Managed PKI configuration.
IMPORTANT! Each time you download a Policy File, you are required to run the install customizer command. Be aware that the customizer command for subsequent configurations uses different syntax than did the customizer command for the initial configuration. This difference is to allow you to run the command without overwriting your modified pages. 1 2
Run the Managed PKI Policy Wizard and download the Policy File. Put the Managed PKI CD in the CD drive. On the UNIX or DOS command line, go to the CD drive, then to the directory that has the name that matches the operating system you are using. Still on the command line, run the customizer (install-<nt|sun|hpux|aix>) command using the following syntax:
install-<nt|hpux|sun|aix> <source dir> <dest dir> <policyfile>
Note
Type the entire path name for the source, destination, and Policy File.
where the source directory and destination directory are the same. The command overwrites the correctly edited files back onto themselves. The following examples show sample commands for Microsoft Windows, Sun Solaris, HP-UX, and AIX:
12
BT38-MPKI6-TRF-V1.1
These examples assume D: is your CD drive and the ACMEBank.policy file is located as indicated in each example.
Note
Example for Windows 2000:

D:\>install-nt C:\VeriSign\OnSite\webroot C:\VeriSign\OnSite\webroot C:\ACMEBank.policy
Example for Sun Solaris:

install-sun /VeriSign/OnSite/webroot /VeriSign/OnSite/webroot /tmp/ACMEBank.policy
Example for HP-UX:

install-hpux /VeriSign/OnSite/webroot /VeriSign/OnSite/webroot /tmp/ACMEBank.policy
Example for AIX:

install-aix /VeriSign/OnSite/webroot /VeriSign/OnSite/webroot /tmp/ACMEBank.policy
BT38-MPKI6-TRF-V1.1
13
14
BT38-MPKI6-TRF-V1.1
CHAPTER 3
Understanding Passcode Authentication

3 ret pahC
VeriSign Managed PKI Passcode Authentication automatically approves and rejects certificate requests by comparing the applicants enrollment data with pre-configured verification data. Passcode Authentication immediately processes and issues certificates, with no intermediate confirmation and approval steps. When an applicant applies for a certificate, the submitted enrollment data (or a subset defined by the Managed PKI administrator) is compared to information in the verification database. The verification database includes a list of all prospective certificate applicants, along with the data that uniquely identifies them. Based upon guidelines established by your organization, the certificate request is either approved or rejected. This chapter includes the following topics: About Passcode Authentication on page 15 Fulfilling Managed PKI Administrator Responsibilities on page 18
About Passcode Authentication

With Passcode Authentication, no additional programming or hardware is required of your organization to automate certificate approval. You configure Passcode Authentication in the Policy Wizard, and BT Trust Services provides the authentication software and stores the verification database. Certificate generation and maintenance operations are hosted at a BT secure site, and your organization is relieved of the time and expense involved in creating and supporting certificate authentication solutions. This option can be used with either BT Trust Services hosting your enrollment pages, or with the Local Hosting option (see Chapter 2, Understanding Local Hosting).
Acquiring a Certificate
With Passcode Authentication, an applicant acquires a certificate as follows:
Figure 3-4 Overview of Passcode Authentication process
Figure 3-5 Underlying data handling for the Passcode Authentication process
When configuring Passcode Authentication in the Policy Wizard, the Managed PKI administrator specifies the fields that an applicant must complete on the certificate enrollment page. These fields are known as match fields. The values entered in match fields are used to identify the person requesting the certificate. Typical match fields are first name, last name, and e-mail address. In addition, the
16
BT38-MPKI6-TRF-V1.1
Chapter 3 Understanding Passcode Authentication
user must enter a passcode to prove their identity. The Managed PKI administrator assigns the passcode to the user and delivers it by an out-of-band mechanism. To install and configure Passcode Authentication, see Managed PKI Installation and Configuration. Once you have installed and configured Passcode Authentication, you may change the verification database stored at BT Trust Services through the Control Center. For example, you can upload additional Comma Separated Value (CSV) files to authorize new subscribers and remove existing entries in the verification database, as needed (see Adding New Applicants to the Verification Database on page 19 and Cancelling Passcodes on page 21). In addition, you can reset passcodes in the verification database (see Resetting Passcodes on page 23).
Step 1
Applicant: Request a certificate.

An applicant requests a certificate by opening the Enrollment Web page and entering his or her enrollment information (including the match values and passcode). The applicant submits the completed page to BT Trust Services.
Step 2
BT Trust Services: Verify the enrollment data

BT Trust Services compares information on the enrollment page with match fields in the verification database. If any of the match field data is incorrect, or if the request duplicates match field data that appeared in a previous request, the request is rejected and the applicant receives a rejection message.
BT38-MPKI6-TRF-V1.1
17
Step 3
BT Trust Services: Approve the request

If the enrollment page data matches the data in the verification database and the passcode for the applicant is correct, the request is approved. Note that subscribers do not receive an approval e-mail.
Step 4
BT Trust Services: Issue a certificate

Following approval, Managed PKI processes the enrollment data and generates a certificate. Then the certificate is signed by the appropriate CA. Once that is done, Managed PKI issues the certificate, sending it to the applicant through HTTPS. Finally, BT Trust Services marks the passcode as used and never uses it again.
Step 5
Subscriber: Install the certificate

After the certificate is issued, it is automatically installed into the subscribers browser.
Fulfilling Managed PKI Administrator Responsibilities

As an administrator, your responsibilities include a number of tasks, some of which appear below. You are likely to have other duties as well. In some companies you also may be responsible for configuring Passcode Authentication for your organization (see Managed PKI Installation and Configuration or Key Management Service Installing Managed PKI with Key Management Service).
Managing Certificates
Depending on your Managed PKI configuration, ongoing administration duties may include the following: Manually processing and reviewing certificate requests. You will not perform this duty if you use the Passcode authentication option. Revoking certificates Updating Certificate Revocation Lists (CRLs) Supporting subscribers Renewing certificates
Updating the certificate directory Monitoring certificate activity To perform some of these tasks, the administrator must have the Certificate Management role. Use the Administrator Roles Wizard to assign roles during installation and configuration (see Managed PKI Installation and Configuration or Key Management Service Installing Managed PKI with Key Management Service).
Implementing and Administering Passcode Authentication

Administrator responsibilities in this area include initial implementation tasks and ongoing tasks to manage Passcode Authentication. Additional details appear in Managed PKI Installation and Configuration. Implementing Passcode Authentication Your responsibilities in this area include: Uploading and maintaining passcode and verification data in the verification database Securely distributing a passcode to each applicant Helping applicants to apply for certificates Once your subscribers have obtained and installed their certificates, you also perform ongoing administrative duties. Adding New Applicants to the Verification Database Occasionally, you will add new applicants to the verification database. For a small number of additions, you may do this manually. For larger groups, you can submit a CSV list (see Adding a Group of Passcodes in this chapter).
Adding an Individual Passcode Manually
On the Certificate Management page of the Control Center, click the Create Passcodes link. The Create Passcode page opens. Passcodes must be a minimum of 4 characters. However, for greater security, passcodes should be a minimum of 8 characters.
Note
BT38-MPKI6-TRF-V1.1
19
Complete the Passcode field, as shown here, and click Submit.

The Passcode Information page shows the match fields you configured. To instruct BT Trust Services to generate the passcode, enter an asterisk (*) in the Passcode field. Otherwise, enter your passcode. All fields except Passcode are case-sensitive. Click Submit. The new information is securely transmitted to BT Trust Services and added to the verification database.
Adding a Group of Passcodes
Follow these steps to add a group of passwords.

1
Generate a new CSV file. The values in this file are added to any that you uploaded previously. The word add must be the first line of the file, as shown:
add #Passcode,Last Name,e-mail Address *,Smith,jsmith@acme.com *,Kim,jkim@abc.edu *,Jones,jjones@xyz.org
Note If your Managed PKI account supports the CEP protocol to enroll for certificates for devices, be sure to include the fully-qualified domain name, IP address values, or both in the CSV file to enable matching on the appropriate value.
20
BT38-MPKI6-TRF-V1.1
On the Certificate Management page, click the Upload Passcodes link. Enter the name and location of the CSV file, or use the Browse button to locate the file.
Click Submit. If the file is configured correctly, the Passcode Operation Complete page opens with a success message. If the file is incorrectly configured, a message details the errors. Correct the errors and resubmit the file.
Changing Managed PKI Configuration Settings Whenever you alter the Managed PKI policy settings for the match fields, you must cancel any unused passcodes and resubmit a new verification file. Cancelling Passcodes Periodically, you may need to cancel passcodes from the verification database. For instance, you may need to cancel a passcode if passcode security has been violated or if potential subscribers no longer have valid reasons for obtaining a certificate. Depending on the number of deletions, you can either cancel passcodes manually for each individual, or submit cancellations as a group in a CSV file. See Resetting Passcodes on page 23 for information on resetting cancelled passcodes.
Note
BT38-MPKI6-TRF-V1.1
21
Canceling an Individual Passcode Manually
Follow these steps to cancel a single passcode.

1
Click the View Passcodes link on the Certificate Management page. The View Passcode search page opens. Specify search criteria and click Submit. The search results show all entries in the verification database that match your search criteria. To read additional information about a passcode before canceling it, click View Details in the Action column. To cancel the passcode, select it and click Cancel in the Action column.
Canceling a Group of Passcodes
You can cancel a group of passcodes by following the identical steps as uploading, except that you use the word cancel in the first line of the CSV file:
1
Generate a new CSV file with entries for each person who must no longer have access to a passcode or certificate.
IMPORTANT!
Use the word cancel in the first line, as shown in this
example:
cancel #Passcode,Last Name,e-mail Address *,Smith,jsmith@acme.com *,Kim,jkim@abc.edu *,Jones,jjones@xyz.org
2 3
On the Certificate Management page, click the Upload Passcodes link. Enter the name and location of the CSV file, or use the Browse button to locate the file. Click Submit. If the file is configured correctly, the Passcode Operation Complete page opens with a success message. If the file is incorrectly configured, a message indicates the errors. Correct the errors and resubmit the file.
4 5
22
BT38-MPKI6-TRF-V1.1
Resetting Passcodes A passcode might become unavailable to an applicant for the following reasons: Repeated attempts to enroll contained incorrect entries, thus exceeding the lockout threshold, triggering lockout, and changing the passcode status to locked. The lockout threshold is the number of times an applicant is allowed to enter a passcode incorrectly before passcode access is frozen. The Managed PKI administrator specifies this value in the Policy Wizard, as well as setting the passcode expiration time period there. See Managed PKI Installation and Configuration.
Note
The Passcode has not been claimed in the time allotted in the Passcode Expiration Period, in which case the passcode status has changed to expired. The Passcode was cancelled by the administrator, thus changing the passcode status to cancelled. When appropriate, administrators can reset locked out, expired, or cancelled passcodes. In addition, you can explicitly set passcodes to particular values (see Setting a Single Passcode to a Specific Value on page 24).
Resetting an Individual Passcode
Follow these steps to reset a single passcode.
BT38-MPKI6-TRF-V1.1
23
On the Certificate Management page, click the View Passcodes link. The View Passcode search page opens.
Enter search criteria and click Submit. The View Passcodes page shows all entries in the verification database that match your search criteria. Select the passcode you want to reset and click Reset from the Action column. This resets the lockout counter and expiration date, and generates a new passcode. Deliver the new passcode to the subscriber in a secure way.
Setting a Single Passcode to a Specific Value
If a passcode has a status of unused, you can replace its current value with a specific value of your choice. Follow these steps to set a specific passcode value.
On the Certificate Management page, click the View Passcodes link. The View Passcode search page opens. Select search criteria and click Submit. The View Passcodes page shows all entries in the verification database that match your search criteria. Select the passcode, and click Edit in the Action column. Change the passcodes current value to the specific value you want and click Continue.
3 4
Renewing Certificates When Using Passcode Authentication As a security precaution, all certificates have a limited lifetime or validity period (also known as the operational period). When a certificates validity period passes, the certificate is no longer valid for access to secure sites and applications. Managed PKI sends a renewal e-mail message to the subscriber. A trusted subscriber can request certificate renewal from the Managed PKI administrator. The Managed PKI administrator reviews the subscriber renewal application and provides a new passcode to the subscriber if they are still entitled to a certificate. The subscriber uses the new passcode to enroll for a new certificate.
Note
The administrator does not need to revoke the expiring certificate.
For more information about renewing certificates, see Managed PKI Administrators Handbook.
BT38-MPKI6-TRF-V1.1
25
26
BT38-MPKI6-TRF-V1.1
CHAPTER 4
Understanding the Automated Administration Feature

4 ret pahC
Both AA and KMS use the Automated Administration functionality to programmatically approve end-user certificates. This chapter defines the components involved in typical installations of Automated Administration and describes how Automated Administration processes certificate requests. For instructions about installing and configuring AA or KMS, see Managed PKI Installation and Configuration or Key Management Service Installing Managed PKI with Key Management Service. This chapter includes the following topics: Introduction on page 27 Understanding the Components of Automated Administration on page 28 Operational Overview on page 32 Native Character Support for Automated Administration on page 33
Introduction
As with Passcode Authentication, Automated Administration enables your organization to approve and reject certificate requests without the involvement of an administrator. Automated Administration automatically compares an applicants enrollment data with information in the verification data source. The verification data source is your organizations already-existing list (ODBC-compliant database, LDAP directory, or flat file) of all prospective certificate applicants along with the unique
BT38-MPKI6-TRF-V1.1
27
data that identifies them. The certificate request is approved or rejected based upon guidelines established by your organization. Although the implementation process for Automated Administration is slightly more complex than installing Passcode Authentication, Automated Administration offers greater flexibility.
Understanding the Components of Automated Administration

This section defines the primary components involved in Automated Administration. Figures 4-6 and Figure 4-7 illustrate these components in typical configurations of Automated Administration. Figure 4-6 illustrates a standalone AA topology with a Local Hosting server host and Automated Administration server (AA server) host. The signing device, vsaasrv (the server software), secure channel communications, and shared libraries that enable communications with the data sources are provided by BT Trust Services.
Figure 4-6 Typical Automated Administration configuration with AA
28
BT38-MPKI6-TRF-V1.1
Chapter 4 Understanding the Automated Administration Feature
Sophialite. Sohialite is a CGI program that facilitates communication between VeriSign Managed PKI or the Certificate Authority (CA) and the enrollment processing application (pestub in Figure 4-6). For more information about Sophialite, see Chapter 14, Working With Sophialite. Local Hosting server. This Web server instance serves the Digital ID Center pages used by applicants to perform certificate services (enroll, search, revoke, and so on). This server receives the enrollment data and forwards it to the AA or KMS server via Sophialite. Automated Administration (AA) server. The AA server takes in enrollment data, determines if a certificate can appropriately be issued by checking the verification data source, encrypts and signs the certificate request, decrypts and signature-checks the certificate response, and stores the certificate in the registration data source. (If KMS is implemented, the KMS server performs these functions.) To facilitate maintenance, you have the option to run two instances of the AA server on a single host, as described in Managed PKI Installation and Configuration. KMS server. (Optional) The KMS server (vskmssrv) enables private key recovery (see Figure 4-7) and performs all of the tasks described for the AA server. If you use KMS, then you do not need to install an AA server. Pestub, vsaasrv, and vskmsrv. Binary files that enable AA to function on Sun Solaris, Microsoft Windows, HP-UX, and IBM AIX systems. These include binary files for both ODBC-compliant databases and LDAP directory access software. pestub enables communication between the Local Hosting server and the AA server. If you are implementing KMS, pestub enables communication between the Local Hosting server and the KMS server. vsaasrv is the AA server software. It enables communications with the verification and registration data sources. vskmsrv (If KMS is used) enables private key recovery for end users and enables communications with the verification and registration data sources
Verification Data Source Shared Libraries. These shared libraries enable the AA or KMS server to use the authentication information in your existing data source (ODBC database, LDAP directory, or flat file) to verify certificate
BT38-MPKI6-TRF-V1.1
29
enrollment data. There is no need to create a new data source for this purpose, instead, you make use of BT-provided shared libraries to enable data handling. Registration Data Source Shared Libraries. These shared libraries enable the AA or KMS server to store certificate information in your existing data source (ODBC database, LDAP directory, or flat file) when a certificate is issued. There is no need to create a new data source for this purpose, instead, you make use of BT-provided shared libraries to enable data handling.
Note
The following sample files for the Microsoft Access ODBC data source may be found on the Managed PKI CD:
- AutoAuth.mdb - sample ODBC data source file for Microsoft Access 97 or 98 - AutoAuth2000.mdb - sample ODBC data source file for Microsoft Access 2000. Signing device. The signing device stores a Registration Authority (RA) private key, which is used to digitally sign all data transmitted from the AA (or KMS) server. The private key for the RA certificate can either be stored in a software library (software signing option), or on a Chrysalis-ITS Luna 2 token (hardware signing option). The default signing device is the software signing option. The hardware signing option provides greater security, however, because the RA private key never leaves the Luna 2 token and it is virtually impossible for an attacker to view the key. With a standalone installation of AA, the signing device resides on the computer that runs the AA server. When KMS is implemented, the signing device resides on the KMS server host.
30
BT38-MPKI6-TRF-V1.1
Figure 4-7 illustrates a typical Key Management Service (KMS) implementation. .
Figure 4-7 Key Management Service architecture
Protecting Sensitive Data

To protect sensitive data, such as user passwords or PINs, you can configure the AA server to exclude certain data from enrollment requests and verification requests sent to BT Trust Services or from being logged in AA or KMS logs. Using the vsaasrv.cfg file (described in Managed PKI Installation and Configuration) or vskmsrv.cfgfile (described in Key Management Service Installing Managed PKI with Key Management Service), configure the fields that you wish to protect.
BT38-MPKI6-TRF-V1.1
31
Operational Overview
This section describes the process of applying for, approving, and retrieving a certificate with Automated Administration.
Figure 4-8 Automated Administration certificate retrieval process

1
Using a browser, an applicant opens the certificate enrollment page on the Local Hosting Web server, and enters the enrollment data and authentication data (a shared secret or PIN). The browser generates the public key, and the applicant then submits the request. The Local Hosting server runs Sophialite, a VeriSign CGI program provided by BT Trust Services. Sophialite calls the AA or KMS server, which then extracts the data from the request and compares it with the authentication data in the verification data source. If the applicants identity is authenticated (confirmed), the request is approved. The AA or KMS server then invokes the signing function to sign the approved request (thus creating a certificate signing request, or CSR). Sophialite forwards the CSR to the BT Trust Services Issuing Center or the Certification Authority (CA).
32
BT38-MPKI6-TRF-V1.1
The BT Trust Services Issuing Center processes the enrollment data and creates a certificate. The certificate and response data are signed with the appropriate BT signers, and are sent to Sophialite. Sophialite calls the AA or KMS server to register this new certificate information in your registration data source. Sophialite sends the certificate to the applicants browser. The browser automatically installs the certificate.
Note
Requests to the AA or KMS server do not automatically generate a Confirmation e-mail message. A pickup e-mail that includes a user PIN number is sent if the request was given a pending (waiting) status and then approved. When a pending Automated Administration request is approved, the certificate is issued immediately.
This is in contrast to non-Automated Administration requests which become certificates only when the user picks them up. This behavior conforms with the CRS protocol. The administrator can use View Certificates to query for the certificate, resend the pick up e-mail, or look at the PIN in View Details. For more information about Automated Administration flow, see Understanding AA Flow Control in Chapter 7, Working with Automated Administration APIs.
Native Character Support for Automated Administration

If you use AA or KMS, you can enable end users to enter data in the major European and Asian language characters in the Digital ID Center certificate management pages. For example, users can enter Traditional Japanese characters in Shift-JIS encoding on the certificate enrollment or search pages. If your Digital ID Center pages accept one character encoding (as specified in the Policy Wizard by the Managed PKI administrator) and the verification and registration data sources support UTF-8 encoding, then you can configure the AA or KMS server to convert data to and from UTF-8. BT Trust Services generates UTF-8-encoded certificates from native-language user input. For more detail, see Chapter 12, Implementing Native Character Encodings with AA or KMS.
34
BT38-MPKI6-TRF-V1.1
CHAPTER 5
Understanding Subscriber Certificate Renewal

5 ret pahC
As a security measure, all certificates have a limited lifetime, or operational period (also known as the validity period). Most certificates have a validity period of one year. When the validity period passes, a subscriber must no longer use that certificate. A trusted subscriber can request renewal of his or her certificate, so he or she can continue using applications that require a certificate. Managed PKI enables you to specify how subscribers and administrators request renewal of their certificates. This chapter includes the following topics: Renewal Methods for Automated Administration Implementations on page 35 Using Automatic Renewal on page 36 Using Re-Authentication Renewal on page 39 Using Client Authentication Renewal on page 39
Renewal Methods for Automated Administration Implementations

For Automated Administration implementations (AA and KMS), Managed PKI supports three methods of subscriber certificate renewal: Automatic renewal Re-authentication renewal Client authentication renewal
BT38-MPKI6-TRF-V1.1
35
Like all Digital ID Center pages with Local Hosting, renewal pages are hosted on your Web server. The default Renewal Notification message sent to subscribers includes a default URL for the renewal pages. Managed PKI administrators can use the E-mail Wizard in the Control Center to replace the default URL with the actual renewal URL. If you have customized your Automated Administration or passcode functions so that the subscriber e-mail address is not included in the enrollment data submitted to BT Trust Services, the system cannot send a renewal notice to each individual subscriber. You must run the Control Center Renewal Wizard, specifying either to not send renewal notices or to send them to a fixed recipient.
Note
You can customize the renewal e-mail that is sent to the user. See Managed PKI Installation and Configuration or Key Management Service Installing Managed PKI with Key Management Service for details. You must also renew your Registration Authority (RA) certificate. (The RA certificate and private key are used to sign certificate signing request (CSR) messages between the AA or KMS server and BT. The private key for the RA certificate is kept on the AA or KMS token.) Before your RA certificates expire, Managed PKI sends a renewal notice to the e-mail address that you specified in the RA enrollment form.
Note
Using Automatic Renewal

The automatic renewal method requires the subscriber to prove that he or she is the person who requested the original certificate. For the subscriber, this process requires only the submission of a renewal request. However, the logistics of the process differ depending on the browser the subscriber uses. If you are using the VeriSign Personal Trust Agent (PTAa certificate-based system that enables subscriber authentication and authorization for Web resources, and transaction-signing and verification), the automatic renewal process is the same for both Microsoft Internet Explorer and Netscape Navigator.If you have implemented Key Management Service (KMS), see the Key Management Service documentation for information on how KMS handles automatic renewal.
Chapter 5 Understanding Subscriber Certificate Renewal
Automatic renewal for Microsoft Internet Explorer users: BT Trust Services sends a renewal notice, including the renewal page URL and renewal ID, to the certificate holder. The page presents the list of certificates in the certificate registry. The subscriber selects the certificate to be renewed, and submits the renewal request. If the certificate is not found, Managed PKI asks the subscriber to re-enroll. If the certificate is found, Managed PKI uses the certificate to sign a certificate proof of possession. The browser then generates a new key pair, and the public key and the certificate proof of possession are sent to BT. In the Key Management Service, the KMS server generates the key pair. Upon verifying the signature, BT Trust Services issues the new certificate and sends it to the browser. The browser loads the new certificate in the certificate registry, and calls the Sophialite CGI program to register the new certificate. Automatic renewal for Netscape Navigator users: BT Trust Services sends a renewal notice, including the renewal page URL and renewal ID, to the certificate holder. When the subscriber goes to the renewal page, Managed PKI asks for the renewal ID, along with the challenge phrase the subscriber entered to enroll for the original certificate. If the challenge phrase entered by the subscriber in the renewal page is incorrect, Managed PKI asks the subscriber to re-enroll. If the challenge phrase is correct, the browser generates a new key pair, and the public key and challenge phrase are sent to BT. Upon verifying the renewal ID and challenge phrase, BT Trust Services issues the new certificate and sends it to the AA or KMS server, as appropriate. The KMS server combines the new certificate and the new private key into a PKCS#12 file. The AA server sends the new certificate to the browser, and the browser registers it. The subscriber sees a success page that provides the location of the PKCS#12 file and what password should be used to unlock it. The subscriber imports the PKCS#12 file into the browser. The browser registers the new certificate. If you are using the VeriSign Personal Trust Agent (PTA), you will not need to manually import the PKCS#12 file into your browser. The renewal process will automatically load the new certificate into Netscape Navigator.
Note
BT38-MPKI6-TRF-V1.1
37
Identifying Re-Used Certificate Fields

For new certificates, the following values remain unchanged from the original certificate: Subject Distinguished Name Validity period Challenge phrase
Addressing Implementation Considerations

For subscribers using Microsoft Internet Explorer, the automatic renewal process is seamlessit requires no input from the subscriber. For subscribers using Netscape Navigator, the subscriber must enter the challenge phrase and renewal ID. Subscribers using Netscape Navigator cannot complete the renewal process for AA or KMS implementations that hide the challenge phrase during the initial subscriber enrollment. If you chose to hide the challenge phrase from applicants during initial enrollment, subscribers using Netscape Navigator must re-enroll.
Note
Once the certificate is sent back to the browser, the Register function in your stub code (pestub, or vsaasrv or vskmsrv) is invoked with the new certificate. You can use the functions provided in the VeriSign Certificate Parsing Module (CPM) to extract the Subject Distinguished Name (DN) and additional information from among other fields. For example, you can parse the DN to build an appropriate key to insert the new certificate into your database. Optionally, if you have implemented the Dual Key option of KMS the end user will get two certificates with the exact same DN, but their key usage extensions will differ. If you extract the key usage extension with the VeriSign Certificate Parsing Module, you can tell the certificates apart. BT Trust Services strongly recommends that you keep old certificates in your database to verify signatures or decrypt data generated in the past by older certificates. VeriSigns Key Management Service can help by securely storing users keys. KMS has significant security advantages over other key-management alternatives, as described in Key Management Service Administrators Handbook.
38
BT38-MPKI6-TRF-V1.1
Chapter 5 Understanding Subscriber Certificate Renewal
Using Re-Authentication Renewal

The process of re-authentication renewal is nearly identical to first-time enrollment. With re-authentication renewal, BT Trust Services sends a renewal notice, including the renewal page URL and the renewal ID, to the subscriber. When the subscriber goes to the renewal page, he or she must re-enter all of the information. The request is then sent to pestub, along with an additional value to indicate that it is a renewal request. From this point forward, the renewal process flow is identical to first-time enrollment. The authentication policies for new enrollment and re-authentication renewal are the same, and no changes are needed for the pestub.cfg, or vsaasrv.cfg or vskmsrv files. As with the Automatic Renewal option, BT Trust Services strongly recommends that you keep old certificates in your database to verify signatures or decrypt data generated in the past.
Using Client Authentication Renewal

In client authentication renewal, BT Trust Services sends a renewal notice, including the renewal page URL, to the subscriber. When the subscriber accesses the URL (on a Web server configured with Client Authentication), Managed PKI asks for the subscribers certificate. The certificate is then sent to the AA or KMS server, along with an additional value to indicate that it is a client authentication renewal request. Upon receiving the request, BT Trust Services issues the new certificate and sends it to Sophialite. Sophialite then registers the certificate with the AA or KMS server, and loads the certificate in the browser. (See Managed PKI Installation and Configuration or Key Management Service Installing Managed PKI with Key Management Service).
Addressing Implementation Considerations

The primary disadvantage of Client Authentication Renewal is that subscribers cannot renew expired certificates. The Web server does not permit expired certificates to access the renewal page.
BT38-MPKI6-TRF-V1.1
39
40
BT38-MPKI6-TRF-V1.1
CHAPTER 6
Understanding Signing Utilities

6 ret pahC
The AA software and hardware signing options (and AA functionality of KMS) come with the following components: For generating keys: swkeygen (software signing) aakeygen (hardware signing)
For importing certificates: swimport This chapter includes the following topics: Using the Software Signing Option swkeygen on page 41 Using the Hardware Signing Option aakeygen on page 42 Importing Certificates swimport on page 43
Using the Software Signing Option swkeygen

The swkeygen utility creates a key pair for the software signing option, saves it in the certificate store, and creates a certificate signing request (CSR) for a Managed PKI administrator RA certificate. If the certificate store is not present, swkeygen creates it. After generating the CSR, swkeygen adds the RA_dn keyword (the unique RA identifier) to the configuration file and comments out the existing keyword. swkeygen Command Syntax
swkeygen <parameters> >racert.req
BT38-MPKI6-TRF-V1.1
41
You can enter swkeygen parameters in any order, but the command must end with > followed by the name of the CSR file to generate (racert.req).
Note
Parameters for swkeygen Command

-name -org -policy (mandatory): <common name> (optional; -org or -policy is required): <Company/Department/Agency> (optional; -org or -policy is required): <the policy file> If you specify -policy, the organization name and division name in the policy file will be used to generate the CSR. If you specify -org and/or -division as well, the values in the policy file will be used and will override the -org and -division values. -division -locality -state -country -config -password (optional): <Division/Organization/Project> (optional): <City/Locality> (optional): <State/Province> no abbreviations (optional): <two-letter country code> (optional): <configuration file> (default is vsautoauth.conf) (optional): <certificate store password> IMPORTANT: The password parameter in the vsautoauth.conf configuration file is the primary method for setting the password. If you wish to use the -password command-line parameter to set the password, then you must comment out the password parameter in vsautoauth.conf before running swkeygen.
Example swkeygen Command The following example produces a CSR named racert.req with Common Name Test, Organization Acme, and Organizational Unit Support:
swkeygen -name Test -org Acme -division Support >racert.req
Using the Hardware Signing Option aakeygen

The aakeygen command creates a key pair on the Chrysalis-ITS Luna 2 token (hardware signing option), saves it in the certificate store on the token, and creates a certificate signing request (CSR) for a Managed PKI administrator RA certificate.
Chapter 6 Understanding Signing Utilities
aakeygen Command Syntax

aakeygen <parameters> >racert.req
You can enter akeygen parameters in any order, but the command must end with > followed by the name of the CSR file to generate (racert.req).
Note
Parameters for aakeygen Command This table lists aakeygen parameters:

-name -org -policy (mandatory): <common name> (optional; -org or -policy is required): <Company/Department/Agency> (optional; -org or -policy is required): <the policy file> If you specify -policy, the organization name and division name in the policy file will be used to generate the CSR. If you specify -org and/or -division as well, the values in the policy file will be used and will override the -org and -division values. -division -locality -state -country -config -password (optional): <Division/Organization/Project> (optional): <City/Locality> (optional): <State/Province> no abbreviations (optional): <two-letter country code> (optional): <configuration file> (default is vsautoauth.conf) (optional): <certificate store password>
Example aakeygen Command The following example produces a CSR named racert.req with Common Name Test, Organization Acme, and Organizational Unit Support:
aakeygen -name Test -org Acme -division Support >racert.req
Importing Certificates swimport

The swimport command imports certificates to the certificate store in PKCS#7 format, or X.509 format. If the certificate store is not present, swimport creates it.
BT38-MPKI6-TRF-V1.1
43
You can also use swimport to display all certificates in the certificate store. This procedure is only used with software signing.
Note
The following statement shows swimport usage:

swimport <parameters>
The following table shows swimport parameters:

Table 6-1 Parameters for the swimport certificate import command
-file -509 -p12 -p12pswd -dump -config -password (optional): <cert file name> (default is PKCS#7 format) (optional): X.509 format (optional): PKCS#12 format (optional): <PKCS#12 file password> (optional): show certificate store (optional): <configuration file> (default is vsautoauth.conf) (optional): <certificate store password>
Note
The swimport parameters may be entered in any order.
The following are several examples of using swimport: The following example imports the PKCS#12 file cert.p12, which is protected by the password mypassword, into the certificate store:
swimport -file cert.p12 -p12 -p12pswd mypassword
The following example imports the PKCS#7 file cert.p7 into the certificate store:
swimport -file cert.p7
The following example imports the X.509 file cert.509 into the certificate store:
swimport -file cert.509 -509
44
BT38-MPKI6-TRF-V1.1
Chapter 6 Understanding Signing Utilities
The following example displays the contents of the certificate store:

swimport -dump
BT38-MPKI6-TRF-V1.1
45
46
BT38-MPKI6-TRF-V1.1
CHAPTER 7
Working with Automated Administration APIs

7 ret pahC
This chapter describes how to work with Automated Administration (AA) application programmable interfaces (APIs). This chapter describes how to use your custom shared library files to add functionality not supported by the BT-provided APIs, and to configure an alternate data source (other than ODBC, LDAP, or flat file). This chapter also describes the regInfo name/value pairs needed to enroll for client certificates (for applications such as S/MIME clients, Web browsers, single sign-on clients), Software Validation certificates, and SSL IDs. Refer to Authentication Services Error Codes and Troubleshooting for a list of the error codes and messages that Automated Administration may return.
Note
This chapter includes the following topics: Understanding AA Flow Control on page 48 Using the Automated Administration APIs on page 50 Using the Verification and Registration API on page 52 Using the Signing API on page 56 Understanding Additional Data Source Configuration on page 67 Using Name/Value Pairs for Enrolling End-Entity Certificates on page 73 Preparing to Enroll for an RA Certificate on page 79 Understanding regInfo Value Tag Definitions on page 81
BT38-MPKI6-TRF-V1.1
47
Understanding AA Flow Control

To help you understand the AA APIs and utilities, this section provides a detailed look at how AA works, and the flow of control between the Local Hosting server, the AA server, and the CA server (VeriSign Managed PKI). Figure 7-9 breaks out the major components of each server.
Figure 7-9 Details of AA components
48
BT38-MPKI6-TRF-V1.1
Chapter 7 Working with Automated Administration APIs
Enrollment and Registration Flow of Control

Figure 7-10 shows how the components communicate with each other to process the certificate request and finally to register the request.
Figure 7-10 End-to-end Automated Administration enrollment flow of control
The end-to-end flow-of-control list that follows corresponds to the numbers in Figure 7-10.
1
The applicant submits the enrollment page. This action posts enrollment and authentication data from the browser to the CGI program (Sophialite). Sophialite calls a verification function using the pestub function in the Communication Library.
Pestub sends the enrollment data behind the firewall to the AA server.
3 4
The AA server queries the verification data source, and returns the verification result. In Figure 7-10, this occurs internally on the AA server (VSAAsrv).
49
BT38-MPKI6-TRF-V1.1
The AA server invokes the signing function to sign the enrollment data and verification result. The AA server returns the signed data to Sophialite. The data excludes any data you have configured as hidden, using the FIELD_HIDE_ATTR parameter in vsaasrv.cfg. Sophialite sends the signed enrollment request and verification result as a PKCSReq to crs.exe running at BT Trust Services. After BT Trust Services generates the certificate, Sophialite receives a CertRep (certificate response) from BT. Sophialite calls a Register function in pestub to update the directory or database with the certificate. the certificate information to the AA server.
10 Pestub sends 11
(Optional) The AA server updates the registration data source with the certificate data. In Figure 7-10, this occurs internally on the AA server and its database. Sophialite returns the certificate to the applicants browser.
12
Using the Automated Administration APIs

This section describes AA application programmable interfaces (APIs) for verification, signing, directory/database updates, and error reporting: Verification and Registration API. This API enables application authorization and prepares enrollment data for submission to the Signing API. Signing API. This API uses the software signing option or the optional Luna hardware to sign authenticated enrollment data so that it can be forwarded to BT Trust Services for certificate generation.
Understanding Data Structures and Definitions

Enrollment information is conveyed by an array of name/value pairs. For example, if the applicants name is John Smith, the following two name/value pairs represent this information:
1
name: mail_firstName, value: John
50
BT38-MPKI6-TRF-V1.1
name: mail_lastName, value: Smith
You can design the enrollment form to include only the minimum number of fields required to authenticate the applicant. After the applicant is authenticated by the database lookup, you can use values from the database to set values for other fields in the name/value pair set that is sent to BT Trust Services as the CSR (certificate signing request) file. These values can be held in a hidden variable in the VHTML form, as it is updated by Sophialite before submission to BT. To protect sensitive data, such as user passwords and PINs, you can configure name/value pairs that will be excluded from communications sent to BT. You configure these name/value pairs in the Signer Config section of the vsaasrv.cfg file. These values are removed after the verification process. Table 7-2 specifies the enrollment data required in a complete certificate request. Fields that are marked as configuration are specified as required or optional when the administrator runs the Policy Wizard. The Field Category column refers to the groups of fields created by the Certificate Administrator during the Certificate Enrollment page configuration process.
Table 7-2 Supported name keywords
Field Name mail_middleName mail_firstName mail_lastName mail_email jobTitle mailStop employeeID additional_field3 to additional_field6 challenge locality Field Category Standard Standard Standard Standard Standard Standard Standard Customized Standard Standard Description Applicant middle name Applicant first name Applicant last name Applicant e-mail address Applicant job title Applicant mail stop Applicant employee ID Customized additional fields Challenge phrase City, town, and so on Required Required Configurable Configurable Configurable Configurable Configurable Configurable Required/ Optional Optional
BT38-MPKI6-TRF-V1.1
51
Table 7-2 Supported name keywords (Continued)

Field Name state country user_data_1 to user_data_3 Field Category Standard Standard AA-specific Description State, province, and so on Country Used for private extensions or DN components that are not part of the standard profile Required/ Optional Configurable Configurable N/A
If the Certificate Administrator used the Control Center Policy Wizard to create custom certificate fields, these fields are held in variables named additional_field4, additional_field5, and additional_field6.
Understanding VSAA_NAME
The VSAA_NAME structure stores a name/value pair. These name/value pairs are used to communicate enrollment information.
typedef struct { char *pszName ; char *pszValue ; } VSAA_NAME ; VSAA_STATUS
The VSAA_STATUS enum returns the verification result.
Using the Verification and Registration API

Upon invocation, Sophialite calls ProcessEntries(), a function in pestub, to perform requested operations from the browser. The following table describes the ProcessEntries function.
Table 7-3 Process entries table
Syntax Description
VSAA_STATUS Process Entries (VSAA_NAME anInput [],VSAA_NAME** panOutput);

The ProcessEntries function processes arrays of name/value pairs from Sophialite for presentation to the request processing application, and vice versa.
52
BT38-MPKI6-TRF-V1.1
Table 7-3 Process entries table (Continued)

Input anInput Contains the input name/value pairs that are processed by the API. The first name/value pair in this list is always {operation, xyz}. The value for operation can be specified by the input HTML page or by the redirecting server. The arrays of VSAA_NAME are always terminated with an empty entry (specifically. a struct in which pszName and pszValue are NULL). Do not delete or free any of the strings passed as input. Contains the output of processing, and can contain an entirely new set of name/value pairs, which is used to substitute the variables in the output HTML page. The base64encoded PKCS#7, which results from signing the verified enrollment information can be one of these name/value pairs. BT Trust Services expects the signed base64encoded PKCS#7 in a name/value pair called csr. The last pair in the list must be {NULL,NULL}. Responsible for calling VSAA_EncodePKCSReq after verification to digitally sign the enrollment request and verification result.
Output
panOutput
Related Functions Example Code
ProcessEntries
pestub.cpp
Understanding ProcessEntries Operations

The operations defined for the ProcessEntries functions can be grouped into three different occurrences. The first occurrence can be any one of the following operations: Applicant Enrollment Authentication Certificate Pickup Certificate Renewal Certificate Revocation The Decrypt operation also occurs with one of the above-listed operations. Lastly, depending on the outcome of the operation, one of two operations occurs next:
BT38-MPKI6-TRF-V1.1
53
Certificate Registration Error Notification The following sections of this document break down each of the operations listed above into a series of steps. Where appropriate, the text indicates whether the code in the step is modifiable or must be used as written. Understanding Applicant Enrollment Authentication Applicant authentication is invoked after the applicant clicks the Submit button to enroll for a certificate. The operation value is defined as AutoAuthOSUserSubmit.
1
The applicant request can be authenticated by extracting data from the name/value pair listed in the request form and by comparing it with your authentication data. If you have configured name/value pairs to hide from BT Trust Services, these values are removed after verification.
If the applicant is authenticated, the function could augment additional name/value pairs to the list of input name/value pairs. (All available names are listed in Table 7-2.) Next, augment or change the value of authenticate to YES. If the applicant is not authenticated and there is no need for the Certificate Administrator to review the request, then the function returns VSAA_VERIFY_FAILED. If the Certificate Administrator needs to review the request, then augment or change the value of authenticate to NO or PENDING. VSAA_EncodePKCSReq() is invoked with all applicant-entered name/value pairs. If any error is detected during these steps, an appropriate VSAA_STATUS value is returned.
Understanding Certificate Pickup This operation is invoked after the applicant clicks the Submit button to pick up a certificate. The operation value is defined as permanent. This code must be used as written.
1
VSAA_EncodeGetCert() is invoked with all applicant-entered name/value pairs and augmented name/value pairs.
BT38-MPKI6-TRF-V1.1
54
The output VSAA_NAME array is returned, as well as the return code of the VSAA_EncodeGetCert() function.
Understanding Certificate Renewal This operation is invoked after the applicant clicks the Submit button on the renewal page. The operation value is defined as userRenewal. If you have chosen automatic renewal, the code must be used as written.
1
VSAA_EncodePKCSReq() is invoked with all applicant-entered name/value pairs. The output VSAA_NAME array is returned, as well as the return code of VSAA_EncodePKCSReq() function.
Understanding Certificate Revocation This operation is invoked after the applicant clicks the Submit button to revoke a certificate. The operation value is defined as do user revoke. This code must be used as written.
1
VSAA_EncodeRevReq() is invoked with all applicant-entered name/value pairs and augmented name/value pairs. The output VSAA_NAME array is returned, as well as the return code of VSAA_EncodeRevReq() function.
Understanding Certificate Registration This operation is invoked just before the certificate is installed on the applicants browser. The value of the operation name/value pair is register. This code may be modified.
1
Optionally, to update your database you can extract the certificate, certificate serial number, and applicant name from the applicant-entered name/value pair. Create a list of one VSAA_NAME entry for output. The entry contains NULL values. Return VSAA_SUCCESS.
BT38-MPKI6-TRF-V1.1
55
Understanding Error Notification This operation is invoked if an error is detected after the applicant verification operation is invoked. The value of the operation name/value pair is error_register. This code may be modified.
1
Optionally, you can extract and log the error_status along with the other enrollment information. Create a list of one VSAA_NAME entry for output. The entry contains NULL values. Return VSAA_SUCCESS.
Understanding the Decrypt Operation This operation is invoked by Sophialite to verify and decrypt data. The value of the operation name/value pair is ReceiveEncryptResponse. This code must be used as written.
1 2
The VSAA_DecodeCertRep() function is invoked. The output VSAA_NAME array is returned, as well as the return code of VSAA_DecodeCertRep() function.
Using the Signing API

To facilitate implementing and adopting the Certificate Request Syntax (CRS) standard, BT Trust Services provides a VeriSign toolkit with an application programming interface (API) to construct CRS requests and decode CRS responses. The Signing API consists of the following functions:
Table 7-4 Signing API functions
Function VSAA_InitSigner() VSAA_EncodePKCSReq() Operation Initializes the signer. Call before calling any other functions in signing library, except VSAA_SetDebugLog. Given a list of name/value pairs, returns a signed and encrypted CRS PKCSReq message.
56
BT38-MPKI6-TRF-V1.1
Table 7-4 Signing API functions (Continued)

Function VSAA_EncodeGetCert() VSAA_EncodeRevReq() VSAA_EncodeGetCRL() VSAA_EncodePassThru() Operation Given a list of name/value pairs, returns a signed and encrypted CRS GetCert message. Given a list of name/value pairs, returns a signed and encrypted CRS RevReq message. Given a list of name/value pairs, returns a signed and encrypted CRS GetCRL message. Returns a VeriSign extension PassThru message that is constructed from the input name/value pairs. Use the PassThru message to suspend/resume certificate validity. Prepares for termination. Requires no parameters. Call before terminating aasign library. Verify and decrypt the CRS CertRep or RevRep. Free data. Set/unset the debugging log. Send and receive CRS messages to and from crs.exe Extract certificate from PKCS#7. Extract certificate content. Sets the password to be used for accessing the certificate store.
VSAA_CleanupSigner() VSAA_DecodeCertRep() VSAA_FreeName() VSAA_SetDebugLog() VSAA_ExchangeMsg() VSAA_ExtractCert() VSAA_DecodeCert() VSAA_SetPassword()
Using Common name/value pairs

The following tables list additional name/value pairs used as input values for APIs.
Table 7-5 Additional API name/value pairs
Name public_key issuerName O=company, OU=dept, CN=common name Format/Value Description Base64encoded of the public key in either PKCS#10 format or Netscape self-signed format. Name of the issuing certificate authority.
BT38-MPKI6-TRF-V1.1
57
Table 7-5 Additional API name/value pairs (Continued)

Name time Format/Value year month day hour minute second fractionSecond half ASCII Key compromise, CA compromise, Affiliation changes, Superseded, Cessation of operation, Certificate hold, Unspecified TEXT TEXT Description The time value is specified as follows: year month day hour minute second fractionSecond. For example, September 5, 2000 12:30:46 PM is represented as 2000 9 5 12 30 46 Certificate serial number. Reason for revocation.
certSerial reason
comment challenge
Comment associated with a revocation request. Challenge phrase supplied by the user during the enrollment process. It is stored in the BT Trust Services repository and can be used later to revoke a certificate.
Table 7-6 VSAA_InitSigner function

Description Initializes the signer. Call before calling any other functions in aasign library, except the VSAA_SetDebugLog function. If an error occurs, VSAA_InitSigner returns a non-zero status. The AA server must use this function to initialize the Luna 2 token. VSAA_STATUS VSAA_InitSigner (const char *lunaCfgFile); lunaCfgFile Luna configuration file. If NULL is passed, vsautoauth.conf is used.
Syntax Input
Table 7-7 The VSAA_EncodePKCSReq function

Description VSAA_EncodePKCSReq returns a CRS PKCSReq certificate request message that is constructed from the input name/value pairs. If an error occurs, VSAA_EncodePKCSReq returns a non-zero status. Multiple threads or processes can invoke this function concurrently.
58
BT38-MPKI6-TRF-V1.1
Table 7-7 The VSAA_EncodePKCSReq function (Continued)

Syntax VSAA_STATUS VSAA_EncodePKCSReq(VSAA_NAME verifiedEnrollInfo[],VSAA_NAME**signed EnrollInfo,int allInOne,const char*lunaCfgFile); Input verifiedEnrollInfo verifiedEnrollInfo is an array of name/value pairs used to control the content of the issued certificate. In addition to the list of name/value pairs described in Table 7-2, the following name/value pair is required: public_key If allInOne is TRUE, this function initializes and cleans up the signing library. Path name of the signing library configuration file. If NULL is passed, the vsautoauth.conf file is used. signedEnrollInfo is an array of name/value pairs. The following name/value pairs are returned: csr: The final enrollment information is returned as a signed base64encoded CRS PKCSReq message. transaction_id: The Transaction ID of the PKCSReq. nonce: The sender nonce of the generated PKCSReq. VSAA_EncodePKCSReq allocates storage for signedEnrollInfo. The caller is responsible for calling VSAA_FreeName() to free this data after use.
allInOne lunaCfgFile
Output
signedEnrollInfo
Table 7-8 VSAA_EncodeGetCert function

Description VSAA_EncodeGetCert returns a CRS GetCert message that is constructed from the input name/value pairs. Use the GetCert message to retrieve a certificate based on its serial number.
Syntax
VSAA_STATUS VSAA_EncodeGetCert(VSAA_NAME anInput[],VSAA_NAME**signedGetCert, int allInOne, const char*lunaCfgFile);

Input anInput Two name/value pairs are required in the anInput parameter: issuerName: Name of the issuing Certification Authority. certSerial: Serial number for the certificate to be retrieved.
BT38-MPKI6-TRF-V1.1
59
Table 7-8 VSAA_EncodeGetCert function (Continued)

allInOne lunaCfgFile Output signedGetCert If allInOne is TRUE, this function initializes and cleans up the signing library. Path name of the signing library configuration file. If NULL is passed, the vsautoauth.conf file is used. signedGetCert is an array of name/value pairs. The following name/value pairs are returned: csr: CRS GetCert message is returned as a signed base64encoded CRS GetCert message in this value. transaction_id: The Transaction ID of the generated GetCert. nonce: The sender nonce of the generated GetCert. VSAA_EncodeGetCert allocates storage for signedGetCert. The caller is responsible for calling VSAA_FreeName() to free this data after use.
Table 7-9 VSAA_EncodeRevReq function

Description Syntax VSAA_STATUS VSAA_EncodeRevReq(VSAA_NAME anInput[],VSAA_NAME**signedRevokeCert, int allInOne, const char*lunaCfgFile); Input anInput Two name/value pairs are required in the anInput parameter: issuerName: Name of the issuing Certification Authority. certSerial: Serial number for the certificate to be revoked. reason: (Optional) Revocation reason. challenge: (Optional) Challenge phrase used to verify the revocation request. This is the same challenge phrase that the applicant submitted during enrollment. If the challenge value is empty, VeriSign Managed PKI allows you (the Certificate Administrator) to revoke this certificate. comment: (Optional) Comment that can be associated with this revocation request. This comment is displayed in the audit trail for this certificate. allInOne If allInOne is TRUE, this function initializes and cleans up the signing library. VSAA_EncodeRevReq returns a CRS RevReq message that is constructed from the input name/value pairs. Use the RevReq message to revoke a certificate.
60
BT38-MPKI6-TRF-V1.1
Table 7-9 VSAA_EncodeRevReq function (Continued)

lunaCfgFile Output signedRevokeCert Path name of the signing library configuration file. If NULL is passed, the vsautoauth.conf file is used. signedRevokeCert is an array of name/value pairs. The following name/value pairs are returned: csr: CRS RevReq message is returned as a signed base64encoded CRS RevReq message in this value. transaction_id: The Transaction ID of the generated RevReq. nonce: the sender nonce of the generated RevReq. VSAA_EncodeRevReq allocates storage for signedGetCert. The caller is responsible for calling VSAA_FreeName() to free this data after use.
Table 7-10 VSAA_EncodeGetCRL function

Description VSAA_EncodeGetCRL returns a CRS GetCRL message that is constructed from the input name/value pairs. Use the GetCRL message to retrieve a CRL from the Certification Authority.
Syntax VSAA_STATUS VSAA_EncodeGetCRL(VSAA_NAME anInput[],VSAA_NAME**signedGetCert, int allInOne, const char*lunaCfgFile); Input anInput Two name/value pairs are required in the anInput parameter: issuerName: Name of the issuing Certification Authority. time: Used to retrieve the CRL. allInOne lunaCfgFile If allInOne is TRUE, this function initializes and cleans up the signing library. Path name of the signing library configuration file. If NULL is passed, the vsautoauth.conf file is used.
BT38-MPKI6-TRF-V1.1
61
Table 7-10 VSAA_EncodeGetCRL function (Continued)

Output signedGetCRL The CRS getCRL message is returned as a singed base64encoded PKCS#7 message in a signedGetCRL. signedGetCRL is an array of name/value pairs. The following name/value pairs are returned: csr: CRS GetCRL message is returned as a signed base64encoded CRS GetCRL message in this value. transaction_id: The Transaction ID of the generated GetCRL. nonce: the sender nonce of the generated GetCRL. VSAA_EncodeGetCRL allocates storage for signedGetCRL. The caller is responsible for calling VSAA_FreeName() to free this data after use.
Table 7-11 VSAA_EncodePassThru function

Description VSAA_EncodePassThru returns a VeriSign extension PassThru message that is constructed from the input name/value pairs. Use the PassThru message to encode a CRS request message to either suspend or resume a certificate validity. Important: As shipped, AA and KMS do not implement the end-user suspend certificate operation. BT Trust Services discourages using this operation as it incurs a security risk. Because AA and KMS do not check to see if the suspend operation is coming from an administrator or an end-user, if you implement this operation, you must ensure that the application that uses this operation is fully protected against unauthorized access. Syntax Input VSAA_Status VSAA_EncodePassThru(VSAA_NAME anInput[],VSAA_NAME** signedGetCert, int allInOne, const char *lunaCfgFile); anInput Two name/value pairs are required in the anInput parameter: operation with value OSsuspendCert req_status Z to suspend, 'V to resume certificate validity issuerName Name of the issuing Certification Authority certSerial Serial number for the certificate to be suspend or resume. allInOne lunaCfgFile If allInOne is TRUE, this function initializes and cleans up the signing library. Path name of the signing library configuration file. If NULL is passed, the vsautoauth.conf file is used.
62
BT38-MPKI6-TRF-V1.1
Table 7-11 VSAA_EncodePassThru function (Continued)

Output signedGetCRL The PassThru message is returned as a signed base64-encoded PKCS#7 message in signedGetCRL. This function allocates storage for signedGetCRL. signedGetCRL is an array of name/value pairs. The following name/value pairs are returned: csr PassThru message is returned as a signed base64-encoded PKCS#7 message in this value. transaction_id Transaction ID of the generated PassThru. nonce Sender nonce of the generated PassThru. VSAA_EncodePassThru allocates storage for signedGetCRL. The caller is responsible to call VSAA_FreeName() to free this data after use.
Example: To suspend a certificate, use the following name/value pairs:

operation OSsuspendCert req_status Z issuerName OU = VeriSign Class 2 OnSite Individual CA, O = VeriSign certSerial7e794bbcfe8884a09852ee52a4f0a67a
To resume a certificate validity, use the following name/value pairs:

operation OSsuspendCert req_status V issuerName OU = VeriSign Class 2 OnSite Individual CA, O = VeriSign certSerial7e794bbcfe8884a09852ee52a4f0a67a
Table 7-12 VSAA_CleanupSigner function

Description Syntax Prepares for termination. Requires no parameters. Call before terminating aasign library. void VSAA_CleanupSigner(void)
Table 7-13 VSAA_DecodeCertRep function

Description VSAA_DecodeCertRep decrypts and verifies the input data using the signing tool. If an error occurs, VSAA_DecodeCertRep returns a non-zero status.
BT38-MPKI6-TRF-V1.1
63
Table 7-13 VSAA_DecodeCertRep function (Continued)

Syntax VSAA_STATUS VSAA_DecodeCertRep(VSAA_NAME*encryptedText, VSAA_NAME**panOutput, int allInOne, const char*lunaCfgFile); Input encryptedTest allInOne lunaCfgFile Output panOutput Contains the encrypted response from BT Trust Services. If allInOne is TRUE, this function initializes and cleans up the signing library. Path name of the signing library configuration file. If NULL is passed, the vsautoauth.conf file is used. Decrypted name/value pairs. VSAA_DecodeCertRep allocates storage for panOutput. The caller is responsible to call VSAA_FreeName() to free this data after use.
Table 7-14 describes additional name/value pairs returned by the VSAA_DecodeCertRep() function.
Table 7-14 Additional name/value pairs returned by the VSAA_DecodeCertRep function
Name operation Format/Value CertRep RevRep messageStatus Response_Success Response_Failure Response_Pending certOrCRL error_status transaction_id nonce half ASCII half ASCII Base64encoded of the certificate or CRL. VeriSign-defined error status. Request/response Transaction ID. Sender/Receiver nonce. Reply status. Description Reply indicator.
Table 7-15 VSAA_FreeName Function

Description Releases memory returning from previous VSAA_function calls.
64
BT38-MPKI6-TRF-V1.1
Table 7-15 VSAA_FreeName Function (Continued)

Syntax Input void VSAA_FreeName(VSAA_NAME**list); list Contains list of name/value pairs to be freed.
Table 7-16 VSAA_ExchangeMsg Function

Description VSAA_ExchangeMsg sends CRS request messages to crs.exe, and receives a returned CRS response from crs.exe. If an error occurs, VSAA_ExchangeMsg returns a non-zero status. On Sun Solaris, the libsocket.a (-lsocket) library must also be included while linking your program. On Windows, win32sock.dll must be included. Syntax VSAA_STATUS VSAA_ExchangeMsg(const char*pkiclientURL, const char*proxyHost, int proxyPort, const VSAA_NAME *req, VSAA_NAME**rsp); Input pkiclientURL The URL at which crs.exe must be posted. On the pilot environment, the URL is: http://onsite-admin-test.trustwise.com/cgi-bin/crs.exe On production, the URL is: http://onsite-admin.trustwise.com/cgi-bin/crs.exe proxyHost proxyPort req The host name of your proxy server. NULL if there is none. The port of your proxy server. The request name/value pairs containing the csr name/value pair. You can pass the output list name/value pairs of the VSAA_Encode*() functions to this function as-is. The response name/value pairs. This list of name/value pairs is suitable as the input to function VSAA_DecodeCertRep() VSAA_ExchangeMsg allocates storage for rsp. The caller is responsible for calling VSAA_FreeName() to free this data after use.
Output
rsp
Table 7-17 VSAA_ExtractCert Function

Description Syntax VSAA_STATUS VSAA_ExtractCert(const VSAA_NAME*req, VSAA_NAME**rsp); BT38-MPKI6-TRF-V1.1 65 VSAA_ExtractCert extracts the certificate from the PKCS7 construct. If an error occurs, VSAA_ExtractCert returns a non-zero status.
Table 7-17 VSAA_ExtractCert Function (Continued)

Input req The list of name/value pairs that contain the certOrCRL name/value pair. The output name/value pairs list for function VSAA_DecodeCertRep() can be passed as-is to this function. Three name/value pairs are returned: cert_DN: The certificates Subject Distinguish Name. Cert_base64: Base 64 encoding of the X.509 certificate. cert_serial: Half-ASCII encoding of the certificate serial number. VSAA_ExtractCert allocates storage for rsp. The caller is responsible for calling VSAA_FreeName () to free this data after use.
Output
rsp
Table 7-18 VSAA_DecodeCert Function

Description Syntax Input VSAA_DecodeCert extracts content from the certificate. If an error occurs, VSAA_DecodeCert returns a non-zero status. VSAA_STATUS VSAA_DecodeCert(const VSAA_NAME*req, VSAA_NAME**rsp); req The list of name/value pairs that contain cert_base64 name/value pair. The output name/value pairs list for function VSAA_ExtractCert() can be passed as-is to this function. Three name/value pairs are returned: issuerName:The certificates Issuer Distinguished Name. subjectName: The certificates Subject Distinguished Name. cert_serial: Half-ASCII encoding of the certificate serial number.
Output
rsp
notBefore: The start of the certificates validity period. notAfter: The end of the certificates validity period.
VSAA_DecodeCert allocates storage for rsp. The caller is responsible for calling VSAA_FreeName() to free this data after use.
Table 7-19 VSAA_SetPassword Function
The VSAA_SetPassword function applies only to the software signing library.

Description VSAA_SetPassword sets the password to be used for accessing the certificate store. If the certificate stores password is not specified in the configuration file (vsautoauth.conf) this function must be invoked before calling any other functions. If an error occurs, VSAA_ExtractCert returns a non-zero status.
66
BT38-MPKI6-TRF-V1.1
Table 7-19 VSAA_SetPassword Function (Continued)

Syntax VSAA_STATUS VSAA_SetPassword (const char*password); Input Password The password to be used by the signing library for all subsequent calls to access the certificate store.
Understanding Additional Data Source Configuration

Although you can configure AA for ODBC, LDAP, and flat-file data sources by making minor changes to the AA server configuration file (vsaasrv.cfg), AA server software enables you to use custom verification shared libraries, registration shared libraries, or both in place of those provided by BT Trust Services. For example, you may need to add functionality not supported by BT-provided VeriSign APIs (such as adding a timestamp to data entries), or to configure alternate data sources (other than ODBC, LDAP, or flat file). The common/include/vsaaapi.h header file defines all APIs that the AA server (vsaasrv.exe) uses. The vsaaldap, vsaaodbc, and vsaafile shared libraries (.dll, .so, or .sl files) provided by BT implement those APIs (listed in the following table).
Table 7-20 APIs used by the AA server
API Initialize() VerifyUser() Description Performs any required initialization on the shared libraries Verifies user requests. This function is required only if implementing the verification function. This function is called before sending enrollment, pickup, revoke, or renew requests to BT Trust Services. VerifyUser( ) performs any specified operations before sending the request to BT Trust Services. You specify the operations to perform in the Service Type Config section of vsaasrv.cfg file. RegisterUser() Publishes a certificate to the storage defined in the user's module. This function is required only if implementing the registration functionality. This function is called after receiving a response from BT Trust Services. ErrorUser() Finalize() BT38-MPKI6-TRF-V1.1 Reports user input errors in log file Is called by the server when the shared library is unloaded 67
The values of VER_SERVICE_DLL and REG_SERVICE_DLL in the vsaasrv.cfg file specify which shared libraries vsaasrv.exe uses for verification and registration, respectively.
As shown above, vsaasrv.exe dynamically loads the specified shared libraries and calls APIs from each shared library as required. The loaded shared libraries specify the procedure entry points for the APIs. VER_SERVICE_DLL indicates the shared library to be used for verification (using the VerifyUser() API). REG_SERVICE_DLL specifies the shared library to be used for registration (using the RegisterUser() API).
VerifyUser( ) Function
The VerifyUser( ) function receives name/value pairs and verifies user requests. This function is required only if implementing the verification function. This function is called before sending enrollment, pickup, revoke, or renew requests to BT Trust Services. VerifyUser( ) performs any specified operations before sending the request to BT Trust Services. You specify the operations to perform in the Service Type Config section of vsaasrv.cfg.
68
BT38-MPKI6-TRF-V1.1
The AA server allows you to encapsulate verification steps (calling the VerifyUser() function) in the shared library (vsaaodbc, vsaaldap, or your own library based on vsaacust) and control when it is invoked. This functionality is controlled by three configuration parameters in the vsaasrv.cfg configuration file: PRE_PICKUP_PROCESS, PRE_REVOKE_PROCESS, and PRE_RENEWAL_PROCESS (all are set to OFF by default). With these variables set to OFF, all name/value pairs for pickup, revocation, and renewal pass through the verification module without change. If any are set to ON, the appropriate verification function (DoPrePickUpProcess(), DoPreRevokeProcess(), or DoPreRenewalProcess() is invoked. You put your custom verification steps within these functions in the shared library. In this way, all custom code can reside within the shared library and not in the vsaasrv main code. This makes future AA upgrades easier and less risky. The pseudo-code that follows describes the functionality within the vsaasrv main routine and the shared libraries. If you are not using a customized data source module, keep the default value of OFF for these parameters.
Note
Example Implementations of Custom Code in Shared Libraries For examples of how to implement these functions, see the appropriate CPP file: vasscust.cpp, vsaafile.cpp, vsaodbc.cpp, or vsaaldap.cpp. All name/value pairs entered by users are sent through the VerifyUser() function before being included in the CSR, signed, and sent to BT Trust Services (except for the ReceiveEncryptedResponse, register, and error_register operations, whose data is sent to other functions). Pseudocode of vsaasrv Main Routine
if operation == VSAA_AA_SUBMIT || operation == VSAA_AA_PICKUP || operation == VSAA_AA_REVOKE || operation == VSAA_AA_RENEWAL { // Perform verification steps first call VerifyUser() // see function below sign data and return it to sophialite to send to VeriSign }
BT38-MPKI6-TRF-V1.1
69
else if operation == VSAA_REGISTER { // This operation indicates that the certificate is downloaded call RegisterUser() } else if operation == VSAA_ERROR_OP { // This operation indicates that the submission process // encountered an error call ErrorUser() }
Pseudocode of VerifyUser Function in vsaaldap.cpp, vsaaodbc.cpp, and vsaacust.cpp

VerifyUser() { if operation == VSAA_AA_PICKUP { // certificate pickup if PrePickupProcess is set to "ON" in vsaasrv.cfg { call DoPrePickupProcess() } } else if operation == VSAA_AA_REVOKE { // certificate revocation if PreRevokeProcess is set to "ON"in vsaasrv.cfg { call DoPreRevokeProcess() } } else if operation == VSAA_AA_RENEWAL { // certificate renewal if PreRenewalProcess is set to "ON"in vsaasrv.cfg { call DoPreRenewProcess() } } else { // for any operation other than pickup, revoke, renewal call DoVerifyUser() } } DoPrePickupProcess () {
70
BT38-MPKI6-TRF-V1.1
// insert your custom verification steps here } DoPreRevokeProcess () { // insert your custom verification steps here } DoPreRenewProcess () { // insert your custom verification steps here }
Using Custom Shared Libraries

If you cannot use the ODBC database, LDAP directory, or flat-file based authentication solutions provided by Automated Administration, you can implement your own data source by writing your own shared libraries. To use custom shared libraries to provide verification and/or registration functionality, replace the default shared libraries with your custom libraries, as shown below.
Figure 7-11 Replacing default libraries

Follow these steps to use custom shared libraries:

1
Create the custom shared libraries. You have the following options: Start with the src/vsaacust/src/vsaacust.cpp template file (this file includes the above-mentioned stub APIs). Modify the example functions as required. The BT-provided LDAP and ODBC shared libraries are examples of adaptations of vsaacust.cpp. To save time, you may want to start with these files rather than writing the functions from scratch using vsaacust.cpp. Source code appears in the directories named src/vsaaldap/src and src/vsaaodbc/src. The source code also provides a Microsoft Visual C++ project file for Windows, and makefiles for Sun Solaris, HP-UX, and AIX. Building components under the vsaacust directory produces a shared library called vsaacust (.dll, .so, or .sl). You can change the makefile or Visual C++ project file to specify a different output library name.
Note Specific instructions for compiling with different releases of Sun Solaris are in Managed PKI Installation and Configuration or Key Management Service Installing Managed PKI with Key Management Service. 2
In this step, modify the configuration settings (or add a new section) in vsaasrv.cfg for your verification and/or registration data source. vsaasrv.cfg includes a configuration section for each type of service module (flat file, ODBC, and directory service) supported by Automated Administration. The corresponding shared libraries are shipped with the Automated Administration package. Modify the configuration settings as required. The Initialize() API in your custom library uses these settings. In vsaasrv.cfg, set the values of VER_SERVICE_DLL and REG_SERVICE_DLL to your shared library names. Start vsaasrv.exe. Automated Administration now uses the custom verification and/or registration module(s).
72
BT38-MPKI6-TRF-V1.1
Using Name/Value Pairs for Enrolling End-Entity Certificates

The section describes the regInfo name/value pairs needed to enroll for Enterprise End Entity certificates for applications (such as S/MIME clients, Web browsers, single sign-on clients). This section also includes details about what information is needed to enroll for IPSEC certificates, and Software Validation certificates.
Using regInfo Content Details for Personal Client Certificates

A key pair and a corresponding PKCS#10 request are generated and placed into a PKCSReq message. Using Subject DN Attributes The subject DN may include the following attributes:
Table 7-21 DN attributes for personal client certificates
Name Attribute organization organizationalUnit title commonName e-mailAddress Attribute Tag PrintableString or T61String PrintableString or T61String PrintableString or T61String PrintableString or T61String IA5String Max Length 64 64 64 64 64 Required Required Optional Required Optional
BT38-MPKI6-TRF-V1.1
73
Using Enrollment Name/Value Pairs The regInfo enrollment must contain the following name/value pairs.
Table 7-22 regInfo enrollment name/value pairs for personal client certificates
Name corp_company Value Tag TEXT Mandatory / Optional mandatory Description Used along with the org_unit value to construct the jurisdiction value of the Managed PKI Account. Restrictions This value is determined during Managed PKI Enrollment This value is determined during Managed PKI Enrollment
org_unit
TEXT
mandatory (but may be empty)
Used along with the corp_company value to construct the jurisdiction value of the Managed PKI Account. Value must be end-user. A yes value causes the mail_email value to be placed in the e-mail attribute of the DN. Specifies the commonName attribute in the DN. If a commonName attribute is specified in the PKCS#10 request, it overrides this value. This value is placed in the e-mail attribute of the DN, if embed_email has yes value. If an e-mailAddress attribute is specified in the PKCS#10 request, it overrides this value.
cert_type embed_email
TEXT TEXT
mandatory optional
YES or NO. If not present, default is YES.
common_name
TEXT
mandatory
mail_email
e-mail
mandatory
mandatory, use the embed_email name/value pair to specify if it must be included in the DN or not.
jobTitle
TEXT
optional
This value is placed in the Title attribute in the DN. If a title attribute is specified in the PKCS#10 request, it overrides this value.
74
BT38-MPKI6-TRF-V1.1
Table 7-22 regInfo enrollment name/value pairs for personal client certificates
employeeID TEXT optional This value is placed in an Organizational Unit attribute in the DN. This value is placed in an Organizational Unit attribute in the DN. This value is placed in an Organizational Unit attribute in the DN. This value is placed in an Organizational Unit attribute in the DN. This value is placed in an Organizational Unit attribute in the DN. This value is a challenge phrase supplied by the user during the registration process. A hash of this value is stored in the repository and may be used later to revoke or renew a certificate. This value is not checked if the RevReq message is signed by a BT Trust Services issued RA certificate. If a challengePhrase attribute exists in the PKCS#10 requests, the value of this attribute overrides the value specified in this name/value pair. This value is used to indicate whether a certificate must be issued (YES), rejected (NO), or queued (PENDING). All End Entity to CA enrollments automatically are placed in the Pending queue for further processing. MAXLENGTH =32
mailStop
TEXT
optional
additional_field4
TEXT
optional
additional_field5
TEXT
optional
additional_field6
TEXT
optional
challenge
TEXT
Optional for RA enrollments. Mandatory for end entity enrollments.
authenticate
TEXT
Mandatory for RA enrollments. Not Applicable for end entity enrollments.
YES, NO, or PENDING
BT38-MPKI6-TRF-V1.1
75
Using Renewal Name/Value Pairs The following table lists reginfo renewal name/value pairs.
Table 7-23 reginfo renewal name/value pairs for personal client certificates
Name corp_company Value Tag TEXT Mandatory / Optional mandatory Description Used with the org_unit value to construct the jurisdiction value of the Managed PKI Account. Used with the corp_company value to construct the jurisdiction value of the Managed PKI Account. Value must be end-user. Value must be renew. The method of renewal. renew autoAuth, pkcs7, or renewalID Restrictions This value is determined during Managed PKI Enrollment This value is determined during Managed PKI Enrollment
org_unit
TEXT
cert_type lifecycle_request getMethod
TEXT TEXT TEXT
mandatory mandatory mandatory
USER_CERT
BASE64
mandatory for autoAuth getMethod mandatory for pkcs7 getMethod
This value contains the base 64 encoded certificate to be renewed. This value contains the base 64 encoded PKCS#7 message representing the signature of the value specified in detachedMesg. This signature must be created using the certificate to be renewed. Data to be signed by the certificate to be renewed. This can be any string (specifically Renew me)
pkcsInformation
BASE64
detachedMesg
TEXT
mandatory for pkcs7 getMethod mandatory for renewaID getMethod mandatory for renewalD getMethod
secretCode
TEXT
Renewal ID.
challenge
TEXT
Challenge phrase associated with the certificate being renewed. BT38-MPKI6-TRF-V1.1
76
Using regInfo Content Details for IPSEC Certificates

A key pair and a corresponding PKCS#10 request are generated and placed into a PKCSReq message. subjectAltName and keyUsage extension values can also be conveyed using the ExtensionReq attribute in the PKCS#10. The subjectName in the PKCS#10 is the subjectName in the resulting certificate. Using reginfo Enrollment Name/Value Pairs The regInfo must contain the following name/value pairs.
Table 7-24 reginfo enrollment name/value pairs for IPSec certificates
Name corp_company Value Tag TEXT Mandatory / Optional mandatory Description Used along with the org_unit value to construct the jurisdiction value of the Managed PKI Account. Used along with the corp_company value to construct the jurisdiction value of the Managed PKI Account. Value must be ipsec. This value is displayed in the Control Center UI and is used for identification. It may be the same value as the commonName attribute in the PKCS#10 subject. A yes value causes the mail_email value to be placed in the e-mail attribute of the DN. This value is used for certificate management notification messages, such as a response to an end-user request for a certificate or certificate renewal. YES or NO. If not present, default is YES. Restrictions This value is determined during Managed PKI enrollment This value is determined during Managed PKI enrollment
org_unit
TEXT
mandatory
cert_type common_name
TEXT TEXT
mandatory optional
embed_email
TEXT
optional
mail_email
e-mail
mandatory
BT38-MPKI6-TRF-V1.1
77
Table 7-24 reginfo enrollment name/value pairs for IPSec certificates (Continued)
challenge TEXT Optional for RA enrollments. Mandatory for end entity enrollments. This value is a challenge phrase supplied by the user during the registration process. A hash of this value is stored in the repository and may be used later to revoke and renew a certificate. This value is not checked if the RevReq message is signed by a BT Trust Services issued RA certificate. If a challengePhrase attribute exists in the PKCS#10 requests, the value of this attribute overrides the value specified in this name/value pair. This value is used to indicate whether a certificate must be issued (YES), rejected (NO), or queued (PENDING). All End Entity to CA enrollments automatically are placed in the pending queue for further processing. MAXLENGTH=32
authenticate
TEXT
Mandatory for RA enrollments. Not Applicable for end entity enrollments.
YES, NO, or PENDING
Table 7-25 reginfo renewal name/value pairs for IPSec certificates

Name corp_company Value Tag TEXT Mandatory / Optional mandatory Description Used along with the org_unit value to construct the jurisdiction value of the Managed PKI Account. Used along with the corp_company value to construct the jurisdiction value of the Managed PKI Account. Value must be ipsec. Value must be renew. The method of renewal. renew autoAuth, pkcs7, or renewalID Restrictions This value is determined during Managed PKI Enrollment This value is determined during Managed PKI Enrollment
org_unit
TEXT
cert_type lifecycle_request getMethod
TEXT TEXT TEXT
mandatory mandatory mandatory
78
BT38-MPKI6-TRF-V1.1
Table 7-25 reginfo renewal name/value pairs for IPSec certificates (Continued)
USER_CERT BASE64 mandatory for autoAuth getMethod mandatory for pkcs7 getMethod This value contains the base 64 encoded certificate to be renewed. This value contains the base 64 encoded PKCS#7 message representing the signature of the value specified in detachedMesg. This signature must be created using the certificate to be renewed. Data to be signed by the certificate to be renewed. This can be any string (specifically Renew me)
pkcsInformation
BASE64
detachedMesg
TEXT
mandatory for pkcs7 getMethod mandatory for renewaID getMethod mandatory for renewalD getMethod
secretCode
TEXT
Renewal ID
challenge
TEXT
Challenge phrase associated with the certificate being renewed.
Preparing to Enroll for an RA Certificate

All Registration Authorities (RA)sAA servers in this caseare issued a BT Trust Services RA certificate that the signing software uses to sign certificate signing request (CSR) messages and the CA uses to encrypt CSR replies. The RA must create a key pair and a corresponding PKCS#10 request. The process of enrolling using a CSR is described in Chapter 8, CSR-Based Enrollment. All BT Trust Services RA certificates are issued from the VeriSign PCA3 root CA.
BT38-MPKI6-TRF-V1.1
79
IMPORTANT! To bind your RA certificate to your Managed PKI account, you must use the identical case-sensitive text values for organization and orgUnit that you used when you enrolled for the Managed PKI service. Set the attribute values as follows:
- organization: Use the value that you submitted for Company / Department / Agency. - orgUnit: Use the value that you submitted for Division / Organization / Project. Table 7-26 describes each of the RA certificate name attributes.
Table 7-26 RA certificate name attributes
Name Attribute country state locality organization orgUnit commonName Attribute Tag PrintableString PrintableString T61String T61String T61String T61String Max Length 2 128 128 64 64 64 Required? Optional Optional Optional Required Optional Required
80
BT38-MPKI6-TRF-V1.1
Understanding regInfo Value Tag Definitions

The following table defines valid values for regInfo value tag types.
Table 7-27 regInfo value tag definitions
Value Tag Type TEXT Definition Value must use ONLY the following characters: A-Z a-z 0-9 (space) ( ) + , - . / : ; < > @ EMAIL A through Z, a through z, 0 through 9, and the following special characters: ! ( ) + - . / : @ _ [Value must contain only 1 @ and at least 1 . (dot)] A through Z, a through z, 0 through 9, spaces, and the following special characters: !"#$&'()+,-./:;<>@_ 0x0D and all upper 128 characters (This includes most European alphabets). The following characters are not permitted: %*=?[]\^`{}|~ Any 8 bit character string, NULL terminated base64 encoding as specified by RFC1113
T61
CLEAR BASE64
BT38-MPKI6-TRF-V1.1
81
82
BT38-MPKI6-TRF-V1.1
CHAPTER 8
CSR-Based Enrollment
8 ret pahC
This chapter describes the process of applying for, approving, and retrieving a certificate using a certificate signing request (CSR-based) enrollment. A CSR-based enrollment is used for non-browser applications that require certificates and that produce Base64 encoded PKCS#10 CSRs. Figure 8-12 describes the steps involved for a subscriber to enroll for a certificate using an existing CSR on their computer.
Figure 8-12 CSR-based enrollment process

Using a browser, the applicant opens the certificate enrollment page for enrolling with a CSR. The first page of enrollment requests the applicant to locate the CSR on their machine. The applicant selects the Browse button on the first enrollment page, locates the CSR, then continues. The Local Hosting server parses the public key from the CSR and embeds the key in the second enrollment page presented to the applicant. The applicant provides the requested enrollment data for the second enrollment page, then clicks Submit. Only the public key is used from the CSR. The second enrollment page lists the required authentication information and certificate content fields set by the Managed PKI administrator with the Policy Wizard. The second enrollment page does not automatically populate the enrollment fields with information from the CSR. The applicant must provide the information for the fields listed on the second enrollment page. The certificate created by the certificate authority contains the information provided by the applicant. The certificate does not contain information provided by the application-generated CSR other than the public key.
Note
The BT Trust Services Issuing Center processes the enrollment data and signs it with the appropriate signer. A certificate is then created and attached to an e-mail message sent to the subscribing applicant. The subscribing applicant saves the certificate to their machine then installs the certificate according to the instructions for the application that generated the CSR.
84
BT38-MPKI6-TRF-V1.1
CHAPTER 9
Using an ODBC Data Source With Automated Administration or Key Management Service
9 ret pahC
You can use an ODBC database as the registration, verification, and/or recovery data source for use with Automated Administration and Key Management Service. This chapter describes how to set up your ODBC database and environment to support Automated Administration functionality. This chapter includes the following topics: Setting Up an ODBC Data Source on Unix on page 85 Setting Up An ODBC Data Source on Windows on page 87
Setting Up an ODBC Data Source on Unix

1
Obtain the ODBC Connect database driver from DataDirect Technologies for your target database and AA or Key Manager server platform. See Authentication Services Hardware/Software Requirements for supported drivers for each platform. Install the ODBC Connect driver package. Follow the instructions provided with the driver. In general, you will need to:
a b c
Untar ev$OS.tar into a directory datadirect Change as root, cd datadirect/odbc Run ksh unixpi.ksh, and follow the instructions
Setup ODBC environment for the user who will run AA server, which is typically root user. The requirement environment is ODBCINI, and
85
BT38-MPKI6-TRF-V1.1
library path to load ODBC driver libraries. Refer to the driver configuration guide for the setup.
a b
Copy /opt/odbc/odbc.ini to /opt/odbc/system_odbc.ini Edit system_odbc.ini file to add a new block for your database by copying the block for Oracle Wire Protocol. Configure the LIBPATH and ODBCINI environment for test users. For example:
setenv ODBCINI /opt/odbc/system_odbc.ini source /opt/odbc/odbc.csh [for LD_LIBRARY_PATH addition]
Set up ODBC data source for the database that AA or KMS will use. Edit the system_odbc.ini file to add a new block for your database by copying the block for Oracle Wire Protocol. Here is a sample block.
[ODBC Data Sources] DB2 Wire Protocol=DataDirect 4.00 DB2 Wire Protocol Driver ... AutoAuth=DataDirect 4.0 Oracle database for AutoAuth tables ... [AutoAuth] Driver=/opt/odbc/lib/ivora17.so Description=AutoAuth test with DataDirect 4.0 Oracle Wire Protocol LogonID= Password= HostName=aaserver.acme.com PortNumber=1521 SID=sid1 CatalogOptions=0 ProcedureRetResults=0 EnableDescribeParam=0 EnableStaticCursorsForLongData=0 ApplicationUsingThreads=1
VeriSign recommends that you use Wire protocol driver version so that you do not need to install a database client in your AA or Key Manager server host.
Tip
86
BT38-MPKI6-TRF-V1.1
Chapter 9 Using an ODBC Data Source With Automated Administration or Key Management Service
For Unix and AIX: Change all occurrences of

Driver=/opt/odbc/lib/ivora17.so
to
Driver=/opt/odbc/lib/ivora17.sl.
6
Optional: Test ODBC with sample table provided in CD. Create sample tables and data in Oracle server for test. Use sqlplus with vsaaora.sql from the AA or KMS package to add tables and data into your test database. Configure the AA or Key Manager server to use ODBC. Set values for the following variables in the vsaasrv.cfg or vskmsrv.cfg file (respectively) to use the ODBC data source you configured in system_odbc.ini.
VER_REG_DATABASE AutoAuth VER_REG_DBUSERNAME <dbuser> VER_REG_DBPASSWORD <password>
Setting Up An ODBC Data Source on Windows

To use an ODBC-compliant data source n on Windows, you must link the ODBC-compliant data source to Automated Administration or Key Management Service. For specific configuration instructions, refer to the instruction manual provided with your database.
Note 1
The examples below include figures of Microsoft Access 2000.
On the Windows Start menu, select SettingsControl Panel and double-click Administrative Tools. The Control Panel opens. Double-click the ODBC icon. The ODBC Data Source Administrator dialog box opens.
BT38-MPKI6-TRF-V1.1
87
Click the Drivers tab (Figure 9-13) and verify that you have the latest ODBC driver for your database.
Figure 9-13 ODBC Data Source Administrator dialog box

4
Click the System DSN tab (see Figure 9-14).
Figure 9-14 System DSN tab
88
BT38-MPKI6-TRF-V1.1
Chapter 9 Using an ODBC Data Source With Automated Administration or Key Management Service
Click Add. The Create New Data Source dialog box opens (see Figure 9-15).
Figure 9-15 Create New Data Source dialog box

6
Select your database driver and click Finish. The ODBC Microsoft Access Setup dialog box opens. In the ODBC Microsoft Access Setup dialog box, enter a name (for example, Automated Administration Database or Key Management Serive Database) in the Data Source Name field. Ensure that you use the same name that you used in the AA or Key Manager server configuration file. Enter the path for the database files. Refer to the databases instruction manual for procedures.
a
In the Database panel of the ODBC Microsoft Access Setup dialog box, click the Select button. The Select Database dialog box opens (see Figure 9-16).
Figure 9-16 Select Database dialog box

Navigate to the mdb file you will use with Automated Administration and click OK.
Close the open dialog boxes. The ODBC database is now configured for use with Automated Administration or Key Management Service. Configure the AA or Key Manager server to use ODBC. Set values for the following variables in vsaasrv.cfg or vskmsrv.cfg (respectively) to use the ODBC data source you configured in system_odbc.ini.
VER_REG_DATABASE AutoAuth VER_REG_DBUSERNAME <dbuser> VER_REG_DBPASSWORD <password>
10
90
BT38-MPKI6-TRF-V1.1
CHAPTER 10
Using a Flat File for Verification Data

01 ret pahC
This chapter describes the structure and function of validuser.txt, a static verification data file. This chapter includes the following topics: About validuser.txt on page 91 Understanding validuser.txt File Structure on page 92 Understanding How validuser.txt Operates on page 92
About validuser.txt
Since the flat file version of the verification database allows you to test functionality with a defined, simple data source, validuser.txt is useful for initial installations of Automated Administration (AA) or Key Management Service (KMS). However, although a flat file is useful when there are a limited number of participants, it is impractical for most production implementations. The validuser.txt file is intended for testing purposes only. The validuser.txt file and format are not intended for production implementations.
Note
The file is structured as a .txt (plain text) file containing the entry information, usually in the form of a Comma Separated Value (CSV) list. It is useful for entering small amounts of information, but is cumbersome with large numbers of updates. Use validuser.txt with the flat file version of the authentication server, not with the ODBC version.
Note
BT38-MPKI6-TRF-V1.1
91
Understanding validuser.txt File Structure

The validuser.txt file includes lines of the following format. The file is case-sensitive. You must use UPPERCASE letters for responses, as shown in the examples.
CAUTION
The first, third and fifth lines in the following example contain authentication data. The e-mail addresses in the enrollment form trigger Automated Administration to perform the appropriate action for the request (approve, reject, or place in the pending state). This procedure avoids the process of accessing the verification database. The second, fourth and sixth lines in the example contain the authenticate value or augmentation data. The augmentation data is added to the certificate request from the corresponding user, whose e-mail address appears in the flat file data above the authenticate line.
mail_email=approve@verisign.com authenticate=YES mail_email=reject@verisign.com authenticate=NO mail_email=pending@verisign.com authenticate=PENDING
In the example, enrollments with an e-mail address of approve@verisign.com are augmented with the authenticate name/value pair set to YES. This causes the request to be approved, regardless of any other text. Similarly, an e-mail address of reject@verisign.com is augmented with NO, and the request is rejected.
Understanding How validuser.txt Operates

The authentication server reads in the flat file on startup. When the server receives an enrollment request, the server reviews the name/value pairs that have arrived with the request. The server then examines the authentication data lines of the flat file, and checks to see if the enrollment request contains name/value pairs that match the name/value pairs in the file.
92
BT38-MPKI6-TRF-V1.1
Chapter 10 Using a Flat File for Verification Data
The search algorithm is based on finding name/value pairs that start the same as the name/value pairs in the file, and it locates any match that starts with the correct information. For example, a search for mail_firstName=John makes a valid match with a mail_firstName of John, JohnB, Johnson, and so on. If one of the lines has a match, then the server augments the request with the following (augmentation data) line in the flat file. It then signs the request, and sends it back to the Local Hosting server, which forwards it to the processing center. The flat file shown in this example approves John Doe and Jane Doe, rejects John Smith and Jane Smith, and places John Jones and Jane Jones in the pending state.
Example Flat File

mail_firstName=John,mail_lastName=Doe authenticate=YES mail_firstName=Jane,mail_lastName=Doe authenticate=YES mail_firstName=John,mail_lastName=Smith authenticate=NO mail_firstName=Jane,mail_lastName=Smith authenticate=NO mail_firstName=John,mail_lastName=Jones authenticate=PENDING mail_firstName=Jane,mail_lastName=Jones authenticate=PENDING
BT38-MPKI6-TRF-V1.1
93
94
BT38-MPKI6-TRF-V1.1
CHAPTER 11
Understanding Directory Technology (Overview)

1 ret pahC
Managed PKI supports a variety of directory types (as described in Authentication Services Hardware/Software Requirements) for your verification and registration data source and to store published certificates in Automated Administration. Managed PKI supports standard schema attributes and can be customized to meet your needs. Appendix D, Using Netscapes Directory Server with Managed PKI LDIF Files, provides detailed instructions for using Managed PKI LDIF files with Directory Server. This chapter includes the following topics: Introduction on page 95 Understanding X.500 the ISO Standard Directory Architecture on page 97 Understanding LDAP Internet Standard for Directory Access on page 99 Using Windows 2000 with Active Directory on page 100
Introduction
A directory is a specialized type of database that provides information to a user communityfor example, information about employees, such as names, telephone numbers and e-mail addresses, or information about network resources such as printers and routers. Many network applications and utilities rely upon directory services because a directory is designed to respond quickly to high volumes of queries. Unlike most
general-purpose databases, the information in a directory is typically read more often than it is changed. Updates to a directory usually involve only simple changes to a single entry. In contrast, most general-purpose databases are designed to balance many different requirements, typically processing read-then-modify transactions which affect multiple entries. The complex transactions of a general-purpose database require equally complex transaction management or roll back schemes. Such complex schemes are not needed for operating a directory. Many enterprises operate multiple, independent directory services, each based on its own proprietary protocol. Such directory services also require separate administration and maintenance. As the number of applications and utilities relying on directories increases, maintaining separate directories becomes increasingly difficult. The ideal solution is a single directory service using an industry standard protocol to support the entire enterprise. Figure 11-17 on page 97 illustrates such an arrangement. To establish a directory as a centralized information source, all applications the directory supports must share a common means of accessing and interpreting the stored information. This means adopting open, widely supported standards. To increase informations availability and reliability, a directory allows information to be replicated between multiple servers. Unlike a database application which requires absolute consistency between all database replicas, a directory application is typically tolerant of transient inconsistencies.
96
BT38-MPKI6-TRF-V1.1
Chapter 11 Understanding Directory Technology (Overview)
This tolerance leads to replication protocols that are much simpler. In turn, simpler replication protocols facilitate the deployment of large directory systems.
Figure 11-17 The directory service as the hub of a large distributed system
Understanding X.500 the ISO Standard Directory Architecture

X.500 is a comprehensive directory architecture designed under the auspices of ISO and other international standards organizations. In the X.500 model, the basic unit of data is a directory entry, which consists of one or more attribute-value pairs. Each attribute contains data associated with the entry. For example, the e-mail attribute contains the e-mail address of the entry. Here is an example of a directory entry for a fictitious employee named Alice Cryptographer, who works for VerySecure Inc.:
Attribute=Value C=US O=VerySecure Inc. OU=Security CN=Alice Cryptographer alice@verysecure.com BT38-MPKI6-TRF-V1.1 Description Country Organization Organizational Unit Common Name E-mail address 97
Attribute=Value Telephone=(666) 123 4567 UserCertificate= <binary data> PrivateKey=<binary data>
Description Telephone number Alices digital certificate Alices encrypted private key
Some attribute-value pairs in a directory entry are used to comprise the Distinguished Name. The Distinguished Name is a set of data that uniquely identifies a real-world entity, such as a person. The attribute-value pairs of the Distinguished Name comprise the hierarchy of the Directory Information Tree. The Directory Information Tree is simply a conceptual tool used to diagram the attribute-value pairs of the distinguished name. In Figure 11-18, the Directory Information Tree consists of the C, O, OU, and CN attribute-value pairs. Therefore, the Distinguished Name for our example is: C=US; O=VerySecure Inc.; OU=Security; CN=Alice Cryptographer
Figure 11-18 Directory Information Tree
The X.500 Directory Access Protocol (DAP) is the protocol that enables a directory user to access an X.500 directory.
98
BT38-MPKI6-TRF-V1.1
Chapter 11 Understanding Directory Technology (Overview)
Understanding LDAP Internet Standard for Directory Access

Lightweight Directory Access Protocol (LDAP), a simplified version of DAP, is used to access online X.500 directory services. Unlike DAP, LDAP is compatible with TCP/IP. Consequently, LDAP is considerably simpler to implement and deploy. LDAP was originally developed at the University of Michigan. In 1995, the Internet Engineering Task Force (IETF) chartered an LDAP working group and issued an Informational RFC specifying version 2 of the LDAP protocol (LDAPv2). In December 1997, the IETF issued the version 3 LDAP protocol specification and endorsed it as a proposed Internet standard.
Understanding the Schema How a Directory Represents Information

Like a database schema, a directory schema determines how data is represented in the directory. Typically, a directory schema dictates the following: Which attributes are supported (for example, mail, telephone, office number). The type of value associated with each attribute (a mail attribute value has character string type). How attribute values are interpreted (the mail attribute stores an e-mail address). To accommodate the many types of information an enterprise needs, the directory schema must be open and expandible. However, each application must also refer to the same type of data in the same way. In defining the role of a directory as a unified information service, it is important to avoid any conflict between the need to support schema customization for custom applications and the need for uniformity and compatibility. For example, if a data provider adds information to a directory entry using particular attribute identifiers (such as mail and userCertificate), clients are unable to retrieve the information unless they use the same attribute identifiers. Additional information is in Appendix C, Understanding How BT Trust Services Generates Certificates.
Using Windows 2000 with Active Directory

Active Directory is a Windows 2000 feature used to store user information in a directory called a data store. The directory contains information about such items as security policies, organization units, users, groups, computers, and domains. When Managed PKI is used in a Windows 2000 environment, digital certificates can be published in Active Directory. Computers running Windows 2000 Server or Windows 2000 Professional can use the Windows 2000 Active Directory feature in connecting to their networks through Active Directory Client. The Active Directory client is network client software for computers connecting to Active Directory networks. Microsoft also makes Active Directory software available as an add-on for Windows 98 and Windows 95 users. Correctly installing and configuring the Active Directory feature is very important. Refer to your Windows manuals for further information about installing and configuring Active Directory.
Using Active Directory Server Info

To publish certificates to Active Directory, you must specify the names of the Active Directory servers, (domain controllers) by listing the names of these servers in the Managed PKI configuration process (see Managed PKI Installation and Configuration). The domain controllers use Active Directory Connect (ADC) to make the connection between multiple Active Directories. If you use ADC, you must enter the Active Directory Server names as a list of Active Directory server names, separated by commas, with no spaces.
100
BT38-MPKI6-TRF-V1.1
CHAPTER 12
Implementing Native Character Encodings with AA or KMS

21 ret pahC
If the Managed PKI administrator configures an account for UTF-8 encoding in the Policy Wizard, end users can enter data in UTF-8 encoded characters. MPKI allows end users to enter enrollment data in their native language, and the input is converted to UTF-8 for inclusion in certificates, and optionally converted to UTF-8 data for storage in the registration data source. AA and KMS support native character encodings for all data source types: flat file, ODBC-compliant databases, and LDAP servers (most LDAP servers use UTF-8 encoding to store native character data). Authentication Services Hardware/Software Requirements lists the encodings supported by Managed PKI.
Managed PKI Support for Native Character Encodings

Managed PKI enables you to accept and process user input in native-language characters. By configuring Managed PKI, you can: Enable subscribers to enter their enrollment information in their native language. Enable subscribers, administrators, and all consumers of certificates to view the certificate data in their native language. Certificates are UTF-8 encoded, enabling their conversion and usage by a wide range of UTF-8 enabled applications.
BT38-MPKI6-TRF-V1.1
101
When applications and Web sites read certificates, they convert the certificates UTF-8 data, as needed, into the encoding that they use.
Figure 12-19 Managed PKI and native languages
Managed PKI support for native-language character encodings includes the following: End users can enter native-language characters in the Digital ID Center pages and can view native-language characters in their certificate. You configure the character set that will be used by the pages through the Policy Wizard in the Control Center. You must inform end users that native characters are supported on these pages. For more information, see Managed PKI Installation and Configuration or Key Management Service Installing Managed PKI with Key Management Service. Administrators can view native characters in the Control Center. Automated Administration supports native-language characters, allowing native-language characters to be stored in the registration data source as UTF-8 format.
102
BT38-MPKI6-TRF-V1.1
Chapter 12 Implementing Native Character Encodings with AA or KMS
Same Encoding Required

If you enable UTF-8 encoding, the following must specify the same encoding for proper functioning and display of native-language characters in certificates: End-user input encoding. End users can enter and view data in their native language. This encoding is defined by the Managed PKI administrator in the Policy Wizard. End-user and administrator browser encoding. End users can view native-language characters. The browser encoding may be set to the correct encoding or the browser may be set to not automatically detect the encoding of HTML pages. If auto-detect is off, the Digital ID Center or Control Center pages will transparently set the browser encoding to the proper value. Digital ID Center pages encoding. Native-language characters will display for certificates on the Digital ID Center pages. This encoding is defined by the Managed PKI administrator in the Policy Wizard. Third party applications. Native-language characters will display for certificates in third-party, UTF-8 enabled applications. The application must be set to view UTF-8 characters correctly. Refer to the vendor documentation for that application. If any of the components do not specify the same encoding, errors can occur.
Example Implementation
For example, you want to support a native-language character set in UTF-8 encoding. To implement this scenario: The administrator specifies UTF-8 encoding in the Policy Wizard. This setting becomes the account encoding. The subscriber enters data using native-language characters. The subscribers browser must be set to UTF-8 encoding. The administrators browser must be set to view UTF-8 encoded characters. If you implemented AA or KMS, the data sources must support and be configured for UTF-8 encoding. Refer to the documentation provided with yur data source for information on configuring it for UTF-8 encoding.
BT38-MPKI6-TRF-V1.1
103
ASCII-Only Data
VeriSign requires that the following certificate data be entered as single-byte ASCII characters. Because the ASCII character set is a subset of the other encodings, the AA server passes ASCII-only fields without conversion. Company/Department/Agency Division/Organization/Project E-mail address Country Passcode
104
BT38-MPKI6-TRF-V1.1
CHAPTER 13
Downloading Certificate Revocation Lists

31 ret pahC
BT and VeriSign maintain and publish certificate revocation information in the form of certificate revocation lists (CRLs). The CRL for each Certification Authority (CA) is updated regularly and released to the public. Certificates are revoked when they are no longer valid. For example, a certificate can be revoked if a certificate holder leaves a company or if the security of the certificate has been compromised. The CRL is a signed list of revoked certificates. An application that relies upon certificates must check the current CRL. Most customers download CRLs from BT through the Control Center. However, if you use Certificate Validation Module (CVM) to automatically download CRLs, then you must configure the application with the appropriate URL. This chapter lists the URLs for these CRL Web pages. Procedures for configuring CVM with these URLs are provided in Managed PKI Certificate Validation and Parsing Guide. If you use a third-party application to download and check CRLs, refer to the documentation provided with that application for configuration procedures. This chapter includes the following topics: Accessing CRLs Through Managed PKI Public on page 106 Accessing CRLs Through Managed PKI Private on page 106
BT38-MPKI6-TRF-V1.1
105
Accessing CRLs Through Managed PKI Public

If you have a Managed PKI Public hierarchy, use the following URLs to access the root and intermediate CA CRLs. The encoding and format of your CRL varies based on the application that uses the CRL.
Downloading Production System CRLs

PCA2 root CA CRL (PKCS#7 format) http://onsitecrl.verisign.com/OnSitePublic/pca2.crl PCA2 intermediate CA (PKCS#7 format) http://onsitecrl.trustwise.com/OnSitePublic/LatestCRL PCA2 intermediate CA (X.509 format) http://onsitecrl.trustwise.com/OnSitePublic/LatestCRL.crl PCA2 intermediate CA CRL LDIF file (PKCS#7 in base 64 format) http://onsitecrl.trustwise.com/OnSitePublic/LatestCRL.ldif PCA2 intermediate CA CRL LDIF file (X.509 in base 64 format) http://onsitecrl.trustwise.com/OnSitePublic/LatestCRL.509.ldif
Downloading Pilot System CRLs

Test C2 intermediate CA CRL (PKCS#7 format) http://onsitecrl-test.trustwise.com/OnSitePublic/LatestCRL Test C2 intermediate CA CRL (X.509 format) http://onsitecrl-test.trustwise.com/OnSitePublic/LatestCRL.crl Test C2 intermediate CA CRL LDIF file (PKCS#7 in base 64 format) http://onsitecrl-test.trustwise.com/OnSitePublic/LatestCRL.ldif Test C2 intermediate CA CRL LDIF file (X.509 in base 64 format) http://onsitecrl-test.trustwise.com/OnSitePublic/LatestCRL.509.ldif
Accessing CRLs Through Managed PKI Private

If you have a Managed PKI Private hierarchy, use the following URLs to access the root and intermediate CA CRLs.
106
BT38-MPKI6-TRF-V1.1
Chapter 13 Downloading Certificate Revocation Lists
Downloading Production System CRLs

Enter the name given to the specific area over which the CA exercises authority in the Your Jurisdiction parameter. This name is found in the upper right corner of the Control Center. Private CA CRL (PKCS#7 format) http://onsitecrl.trustwise.com/<YourJurisdiction>/LatestCRL Private CA CRL (X.509 format) http://onsitecrl.trustwise.com/<YourJurisdiction>/LatestCRL.crl Private CA CRL LDIF file (PKCS#7 in base 64 format) http://onsitecrl.trustwise.com/<YourJurisdiction>/LatestCRL.ldif Private CA CRL (X.509 in base 64 format) http://onsitecrl.trustwise.com/<YourJurisdiction>/LatestCRL.509.ldif
Downloading Pilot System CRLs

Private CA CRL (PKCS#7 format) http://onsitecrl-test.trustwise.com/<YourJurisdiction>/LatestCRL Private CA CRL (X.509 format) http://onsitecrl-test.trustwise.com/<YourJurisdiction>/LatestCRL.crl Private CA CRL LDIF file (PKCS#7 in base 64 format) http://onsitecrl-test.trustwise.com/<YourJurisdiction>/LatestCRL.ldif Private CA CRL LDIF file (X.509 in base 64 format)
http://onsitecrl-test.trustwise.com/<YourJurisdiction>/LatestCRL.509.ldif
BT38-MPKI6-TRF-V1.1
107
108
BT38-MPKI6-TRF-V1.1
CHAPTER 14
Working With Sophialite

41 ret pahC
This section is intended for HTML authors using VHTML (Variable HTML) and Sophialite to: Pass information from HTML entry forms to a server-side processing application Return information from the server to the applicant in named variables in HTML pages Present the appropriate HTML pages to the applicant, as determined by the value of a status code returned by the server-side processing application To use Sophialite, you need the following skills: Working knowledge of HTML General understanding of CGI and Web server operations Basic understanding of how to use variables and simple logical expressions in programming This chapter includes the following topics: Understanding Sophialite on page 110 Configuring Sophialite to use a Proxy Server on page 111 Understanding the Form Definition File (FDF) on page 111 Modifying End-User Error Message Text on page 125 Designing Web Pages for Use With Sophialite on page 126
BT38-MPKI6-TRF-V1.1
109
Understanding Sophialite
Sophialite, a CGI program, facilitates transmitting data from a form within an HTML page to a server-side processing application. In addition, Sophialite returns data to named variables in VHTML pages. The named variables are defined in a form definition file (FDF)a text file containing six descriptors per variable. Variable names are used as keys to associate values with the appropriate HTML elements, FDF entries, and database fields in the processing application. Therefore, variable names must be consistently applied to VHTML pages, the FDF, and the database schema of the processing application. If you remove the mail_firstName and mail_lastName fields from the enrollment pages, and make them optional in the corresponding .fdf files, the authentication database supplies the Common Name (CN) for the certificate. When this is the case, the common_name name/value pair takes precedence over mail_firstName and mail_lastName.
Note
A typical implementation of Sophialite includes an HTML-based registration form, a VHTML-based confirmation form, a customer database management application, and a set of HTML pages. The HTML pages are presented to the applicant in the event of errors or problems with the submitted data. As shown in Figure 14-20, Sophialite enables two-way information passing between client and server, while the FDF ensures one-to-one correspondence between VHTML name/value pairs and fields in the customer database.
110
BT38-MPKI6-TRF-V1.1
Chapter 14 Working With Sophialite
Depending on status values returned by the Processing Application (pestub), Sophialite can return either refreshed HTML or a VHTML form containing named values to the client browser.
Figure 14-20 Sophialite operation
Configuring Sophialite to use a Proxy Server

To configure Sophialite to use a proxy server for communication with pkiclient, create a file named sophia.cfg in your cgi-bin directory. In the file, add the following line:
proxy <your proxy server name>[:<proxy port>]
The proxy server name and proxy port must be separated by a colon, with no space before or after the colon. If no proxy port is specified, port 80 is used.
Note
Understanding the Form Definition File (FDF)

The form definition file is a text file that provides a structured definition of a form presented in an associated HTML page. Form definition files are stored in the /fdf directory on the server (parallel to the /cgi-bin directory, in which Sophialite resides). HTML files list their associated
BT38-MPKI6-TRF-V1.1
111
form definition files in an INPUT element within a form (see Designing Web Pages for Use With Sophialite on page 126). Figure 14-21 shows the data process flow for a VHTML/Sophialite system. Sophialite reads the FDF before the HTML page, and then creates a skeleton of the entry list (that is, an unpopulated list). Sophialite then reads the form in the HTML page and compares the data with the named INPUT elements and the named entries in the FDF. By default, the POST target is actually set to softbounce.exe, not sophialite.exe. The softbounce.exe executable is a proxy to sophialite.exe and acts as an additional check to prevent users from passing extra fields to the back end. To use softbounce.exe and pass extra fields, you must edit the enroll_wait.htm file in the htmldocs/client directory.
Note
The FDF contains descriptions of entry variables and status variables. Entry variables are used to pass applicant-entered information from the Web page, through Sophialite, and on to the processing application. Status variables are used to control presentation of pages according to status codes returned by the processing application.
112
BT38-MPKI6-TRF-V1.1
Figure 14-21 Sophialite in operation with FDF files
BT38-MPKI6-TRF-V1.1
113
A status variable has three descriptors. For each type of variable, descriptors are delimited by white space (spaces or tabs), and each variable description is terminated by a carriage return (unless continued to the next line with the + character). Comments can be included, but they must consist of a single line starting with a pound symbol (#). All descriptors must be present for each named variable, except for static values (identified in the sample file shown below). A short form definition file might look like this:
#NAME TYPE REQUIREMENT DEPENDENCY CONTROL
#-----------------------------------------------------------------------email cust_name addr city state postcode phone fax pub_key # phoneOK CONTROL OPTIONAL NONE NONE e-mail e-mail TEXT TEXT TEXT TEXT PHONE PHONE BASE64 MANDATORY MANDATORY MANDATORY MANDATORY MANDATORY MANDATORY OPTIONAL OPTIONAL MANDATORY NONE NONE NONE NONE NONE NONE NONE NONE NONE NONE NONE NONE NONE NONE NONE NONE NONE NONE
The above FDF defines e-mail addresses, names, address information, and public keys as required information, while designating telephone and fax numbers as optional. An optional designation means the form may be processed if the applicant does not provide telephone or fax numbers. Finally, control corresponds to a button the applicant might select on an HTML page to indicate if telephone contact is acceptable. A portion of an HTML page that could work with this FDF might look like this:
114
BT38-MPKI6-TRF-V1.1
Note
This is an incomplete example.
<HTML> ... <FORM ACTION=/cgi-bin/sophialite.exe ENCTYPE=x-www-form-encoded METHOD=POST> ... <INPUT TYPE=text NAME=email SIZE=24> <INPUT TYPE=text NAME=cust_name SIZE=24> <INPUT TYPE=text NAME=addr SIZE=16> <INPUT TYPE=text NAME=city SIZE=16> <INPUT TYPE=text NAME=state SIZE=2 MAXLENGTH=2> <INPUT TYPE=text NAME=postcode SIZE=10 MAXLENGTH=10> <INPUT TYPE=text NAME=phone SIZE=13 MAXLENGTH=13> <INPUT TYPE=text NAME=fax SIZE=13 MAXLENGTH=13>
<INPUT TYPE=checkbox NAME=phoneOK VALUE=Ok to contact by phone>
<KEYGEN TYPE=hidden NAME=pub_key VALUE=> ... </HTML>
The maximum length of values passed to Sophialite is enforced by the HTML page (and presumably by the processing application on the server side), not by Sophialite. Also, the name/value pairs are not order-dependent (the HTML page and FDF can arrange the name/value pairs in different orders).
BT38-MPKI6-TRF-V1.1
115
Understanding Variable Definitions in the FDF

The FDF contains five descriptors for each entry variable, and three descriptors for each status variable. Each descriptor is described below. Using Name (Entry and Status Variables) For entry variables, the name may contain any number of upper- and lower-case letters, numerals, and punctuation characters. However, the characters \, #, +, and % are reserved for special purposes and cannot be included in names. Also, the entry variable name must not contain any white space. Examples of valid names are street_address, Address_1, invoice_PO_number For status variables, the name must be STATUS. Using Type (Entry and Status Variables) The type of variable determines the criteria for error checking (if any) performed on the variables value. The variables type also determines if the value is passed to a processing application on the server. The following table lists valid types for entry variables, along with their associated error checking criteria.
Table 14-28 Valid types for entry variables
Type Description Error Checking Value passed to processing application? Yes
BASE64
A digital certificate represented by Base-64 representation (two ASCII characters per digit). Any characters allowed. Often used for text areas in which applicants enter comments and questions. Used for handling data in the VHTML page itself. Usually radio buttons and checkboxes. 8-digit numeric date in the format mmddyyyy. Can include slash (/) or dash (-) separators.
Value must be a valid Base-64 representation. None
CLEAR
Yes
CONTROL
N/A
No
DATE
Must be numeric, containing only slash or dash separators (/ or -).
Yes
116
BT38-MPKI6-TRF-V1.1
Table 14-28 Valid types for entry variables (Continued)

Type Description Error Checking Value passed to processing application? Yes
DEBIT
Credit card number.
Algorithmically checked to ensure it is a possible credit card number (checking for current validity is the responsibility of the processing application). A through Z, a through z, 0 through 9, and the following special characters: ! ' ( ) + -./:@_ None 0 through 9, spaces, and the following special characters: ( )+ - ./: A through Z, a through z, 0 through 9, spaces, and the following special characters: !"#$&'( )+,-./:;<>@ _.` 0x0D and 0x7F through 0xFF All upper 128 characters. (This includes most European alphabets.) The following characters are not permitted: % * = ? [ ] \ ^ { } | ~
E-MAIL
Standard Internet e-mail address.
Yes
HYBRID PHONE
A control whose value is passed to the processing application. Used for telephone numbers; checked for length and characters. Alphanumeric text including non-US characters
Yes Yes
T61
Yes
TEXT
Alphanumeric data.
A through Z, a through z, 0 through 9, spaces, and the following special characters: '()+,-./:
Yes
Using Requirement (Entry Variables Only) The REQUIREMENT descriptor for entry variables may be MANDATORY or OPTIONAL. A mandatory requirement means a value is required before data can
BT38-MPKI6-TRF-V1.1
117
be passed to the processing application. An optional requirement means that the variable need not contain a value. Using Dependency and Control (Entry Variables Only) The Dependency and Control fields are used together to load values into variables on the basis of the state of one or more controls, and to dynamically determine if the REQUIREMENT descriptor of a variable is MANDATORY or OPTIONAL. The simplest use of Dependency and Control is to designate a variable as OPTIONAL or MANDATORY on the basis of a control. For example, a credit card number would be required when the value of a button is C_Card, and optional when the value is Purchase Order. To accomplish this, the variables REQUIREMENT is set to MANDATORY, DEPENDENCY is set to NONE, and CONTROL contains a logical expression. When the expression evaluates to TRUE, the REQUIREMENT is honored. When it evaluates to FALSE, REQUIREMENT is treated as OPTIONAL. The following FDF entry is an example of how to designate a variable as OPTIONAL or MANDATORY:
#-----------------------------------------------------------------------pmt_type card_num CONTROL DEBIT OPTIONAL MANDATORY NONE NONE NONE pmt_type = C_Card
A more complex use of Dependency and Control can assign the value of one variable to another variable based on a control. For example, the variable biz_phone could be assigned the value of home_phone when the value of a button is Home_Office. To accomplish this, the biz_phone variable is assigned a DEPENDENCY of home_phone. When a logical expression in CONTROL evaluates to TRUE, the value of the home_phone is copied to biz_phone. The following FDF entry is an example of how to assign the value of one variable to the value of another variable:
#-----------------------------------------------------------------------Biz_loc
118
CONTROL
OPTIONAL
NONE
NONE
BT38-MPKI6-TRF-V1.1
biz_phone
PHONE
MANDATORY
home_phone
Biz_loc = Home_Office
The most complex application of Dependency and Control assigns the value from one of two variables to a third variable based on a control. For example, the variable best_num could be assigned the value of home_phone when the value of a button is Call_home, or the value of biz_phone when the buttons value is Call_work. The + character is used as a logical OR to separate the two logical possibilities in the Dependency and Control descriptors. The following FDF entry is an example of how to assign the value from one of two variables to a third variable:
#-----------------------------------------------------------------------Contact best_num CONTROL PHONE OPTIONAL MANDATORY NONE home_phone biz_phone NONE Contact = Call_home + Contact = Call_work
Addressing a Special Case: Using Constant as an Entry Variable Descriptor You can define an entry variable with a static value in the FDF. You do not need to define static entry variables in the HTML file because if the same variable exists in both the HTML and FDF files, the FDF value takes precedence. The following is an example of how to define a constant entry variable:
# # CONSTANT # CONST member_service TWA - Customer Service EnterpriseServiceAdmin
There are three columns in this example. The first column specifies this line as constant entry variable. The second column specifies the name of the variable, and the last column specifies the value. Notice that the value can contain spaces. Using Code (Status Variables Only) The code data is an alphanumeric string representing the hexadecimal error code returned by the processing application. There are no restrictions on the code values; any alphanumeric value is acceptable.
BT38-MPKI6-TRF-V1.1
119
Using Value (Status Variables Only) The value field data is a static alphanumeric string that you define. Placing a filename or URL address in the value field enables the processing application to dynamically locate and display the HTML page associated with a specific status code. For example, if the status code returned is 3001, the value field might contain the pointer prepend.htm. Status variables do not exist within HTML pages. Instead, status variables point to the location of HTML files. The file to which a status variable refers must be local to the server.
Note
The default path to the file is the server URL. For example, if the server URL is http://www.myserver.com/ and the associated file is in the directory /htmldocs/newpages, the value field data would be /newpages/<filename>.
Note
The htmldocs directory is the main directory for the HTML files.
The search path for locating the associated HTML files begins from the cgi-bin directory. The cgi-bin directory resides at the same directory level as the htmldocs directory. If the URL or filename listed in the value field does not begin with ../htmldocs/ the application automatically prefixes ../htmldocs/. The following FDF entries provide for five different status codes returned by the processing application. Each status code results in a unique action.
#NAME CODE VALUE
#----------------------------------------------------STATUS STATUS STATUS STATUS STATUS

Note
3001 4002 5003 6004 6005
prepend.htm ../../hack/replace.htm test/prependPath.htm ../CompDept/asIs.htm ../htmldocs/noChange.htm
The name of a status variable must be STATUS.
120
BT38-MPKI6-TRF-V1.1
The following table provides examples of how value fields map to code values and the location of the associated HTML pages.
Table 14-29 Status code page location
Status Code 3001 4002 5003 6004 6005 Value prepend.htm ../../hack/replace.htm test/prependPath.htm ../CompDept/zapPath.htm ../htmldocs/noChange.htm Location of Page relative to the cgi-bin directory ../htmldocs/prepend.htm ../htmldocs/replace.htm ../htmldocs/test/prependPath.htm ../htmldocs/zapPath.htm ../htmldocs/noChange.htm
The highest level directory for an HTML file is the htmldocs directory. An HTML file may be located in any directory structure within the htmldocs directory.
Note
Formatting the Form Definition File

By convention, the FDF includes entry variables first, followed by status variables (if any), as in this example:
#example.fdf # #######################Entry Variables # #NAME CONTROL TYPE VALUE REQUIREMENT DEPENDENCY
#-----------------------------------------------------------------------name NONE email NONE home_ph NONE work_ph NONE TEXT TEXT PHONE PHONE NONE NONE NONE NONE MANDATORY MANDATORY OPTIONAL OPTIONAL NONE NONE NONE NONE
BT38-MPKI6-TRF-V1.1
121
# # # #######################STATUS Variables # #NAME CODE VALUE
#----------------------------------------------------------STATUS STATUS STATUS STATUS 3001 4002 5003 6004 vErrorPage.html ../trouble/vBigProblemPage.html EntryForm.html http://www.yourco.com/infoPage.html
Avoiding Reserved Name Keywords

If you add parameters to your enrollment pages, there are certain reserved name keywords you cannot use. Table 14-30 lists the VeriSign-reserved name keywords.
Note
Do not change the Type or Requirement for these keywords.
Table 14-30 Reserved name keywords

Field name operation originator application corp_firstName corp_lastName corp_title corp_company org_unit corp_addr corp_city Type Text Text Text Text Text Text T61 T61 Text Text Requirement Mandatory Mandatory Mandatory Mandatory Mandatory Mandatory Mandatory Optional Mandatory Mandatory
122
BT38-MPKI6-TRF-V1.1
Table 14-30 Reserved name keywords (Continued)

Field name corp_state corp_country corp_postal corp_email corp_workPhone corp_faxPhone challenge tech_contact tech_firstName tech_lastName tech_title tech_workPhone tech_email tech_company bill_contact bill_firstName bill_lastName bill_title bill_workPhone bill_email billing_type payment_type debit_number cardExpire_month cardExpire_year card_name BT38-MPKI6-TRF-V1.1 Type Text Text Text E-mail Phone Phone Text Control Text Text Text Phone E-mail T61 Control Text Text Text Phone E-mail Text Hybrid Debit Text Text Text Requirement Mandatory Mandatory Mandatory Mandatory Mandatory Optional Mandatory Optional Mandatory Mandatory Mandatory Mandatory Mandatory Mandatory Optional Mandatory Mandatory Mandatory Mandatory Mandatory Mandatory Mandatory Mandatory Mandatory Mandatory Mandatory 123
Table 14-30 Reserved name keywords (Continued)

Field name invoice_po_number check_number rating mail_firstName mail_lastName mail_email public_key private_label custom_ca_dn product_config_file purchase_quantity cert_type user4_text user5_text user6_text domain1_text domain2_text domain3_text domain4_text remote_host check_domain product_type Type Text Text Text Text Text E-mail Base64 Text Text Text Text Text Text Text Text Text Text Text Text Clear Text Text Requirement Mandatory Mandatory Optional Mandatory Mandatory Mandatory Optional Optional Optional Mandatory Optional Mandatory Optional Optional Optional Optional Optional Optional Optional Optional Optional Optional
124
BT38-MPKI6-TRF-V1.1
Modifying End-User Error Message Text

Each field in an end-user-facing page (for example, the enrollment page) has an expected data format. When a user submits data that does not conform to the required format for a field, a CGI program composes an error page and presents it to the browser. For BT Trust Services-hosted Managed PKI implementations, the CGI program is sophia.exe. For locally-hosted Managed PKI implementations, the CGI program is haydn.exe. Both CGI programs use haydn.edf as the error definition file to define the descriptive text that appears in end-user pages. For example, fields of text data type do not accept the * (asterisk) character. The CGI program returns the following error page when a user enters Johns*n in the Last Name field:
Figure 14-22 Example error page (text defined in haydn.edf)
BT38-MPKI6-TRF-V1.1
125
Editing the haydn.edf File (an Example haydn.edf Code)

You can customize the text and language of error messages by editing the haydn.edf file. Each error message in haydn.edf is defined in two lines. The first line contains two entries: an internal reference to the field used by the HTML and FDF file, and the field name that appears on the end-user error page (Organization/Last Name, in the illustration above). The second line is the descriptive text of the error message. This example text from haydn.edf shows a single entry. The colon after the field name (Organization/ Last Name: in this example) is required.
org_lastName: Organization/ Last Name:
This is a required field. The information entered should contain only alphabetical or numerical characters and please do not use any of these symbols: ! @ $ % ^ & * ( ) ~ _ ? > < / \..
Following Editing Guidelines

Follow these guidelines when editing the haydn.edf file: Error message text that includes multi-byte characters can be displayed only if the users browser is capable of processing the characters. Be careful when changing the message text. Changing one portion of the text may have implications elsewhere. For example, multiple error codes may be mapped to the same message text, making revised message text that is correct for one error incorrect for another error.
Designing Web Pages for Use With Sophialite

Two types of Web pages are generally used with Sophialite: entry forms that pass information from the applicant to Sophialite (and subsequently to a processing application), and VHTML pages that return information to the applicant (for example, to enable them to check the information they entered).
Using the form_file INPUT Element

Every Web page used with Sophialite (that is, both entry forms and VHTML pages) must include a FORM structure in which the ACTION attribute identifies the Sophialite program, and the METHOD attribute is set to POST.
126
BT38-MPKI6-TRF-V1.1
Within the form, a hidden INPUT element named form_file must be included, with its VALUE set to the location (relative to the servers /cgi-bin directory) of the FDF describing the form. For example:
... <INPUT TYPE=hidden NAME=form_file VALUE=../fdf/entryForm.fdf>
This INPUT element enables Sophialite to identify the appropriate FDF for the page. When the only function of the page is to pass applicant-entered information to Sophialite, no VHTML tags are used.
Using the html_file INPUT Element

When more than one HTML page is used (either for applicant entry of additional information, or to return information to the applicant), an INPUT element named html_file must be included. The TYPE of the INPUT element is set to hidden, and its VALUE set to the location of the following page, expressed as a filename (relative to the servers /cgi-bin directory). For example:
... <INPUT TYPE=hidden NAME=html_file VALUE=../htmldocs/vCheckEntry.html> ...
Using Additional INPUT Elements

Depending on the processing application on the server, your HTML page may need additional INPUT elements. The following example shows two of the additional INPUT elements required by the ECAS certificate issuing application:
... <INPUT TYPE=hidden NAME=operation VALUE=C1Submit> <INPUT TYPE=hidden NAME=class VALUE=CLASS1> ...
BT38-MPKI6-TRF-V1.1
127
Using VHTML Tags

With VHTML tags, Web pages may return information to the applicant. VHTML tags are simply variable names enclosed by double dollar sign characters ($$) and placed within a FORM structure in the page. Variable naming must be consistent with the naming used in the FDF and the processing application on the server. However, variables are order-independent, so the VHTML page need not follow the order used in its FDF. The following example shows the values of variables name and e-mail:
<HTML> ... <FORM ACTION=/cgi-bin/sophialite.exe ENCTYPE=x-www-form-encoded METHOD=POST> <INPUT TYPE=hidden NAME=form_file VALUE=../fdf/UserInfo.fdf> <P> You entered this name: $$name$$ <P> You entered this e-mail address: $$email$$ <P> ... </HTML>
128
BT38-MPKI6-TRF-V1.1
CHAPTER 15
Understanding the Browser Emulation Specification

51 ret pahC
This chapter describes the browser emulation protocol used for communication between a PKI-enabled client, and either a VeriSign Managed PKI RA or a VeriSign Managed PKI CA. This document specifies the procedures and protocol information for communicating between the client and the Automated Authentication server (AA Server) or the CA. There are two basic modes of operation in both the interactions between the client and the AA server and between the client and the CAautomatic and manual. The mode of operation is specified in the instructions for running Policy Wizard (see Managed PKI Installation and Configuration). This chapter includes the following topics: (Optional) Tools Used by the Client to Interface with Managed PKI on page 129 Understanding Fundamental Assumptions on page 130 Understanding End Entity Token Generation on page 131 Working with HTTP and MIME on page 131 End Entity Certificate Request Process for Managed PKI on page 133
(Optional) Tools Used by the Client to Interface with Managed PKI

The client can use VeriSign Policy Module (vspolicy.dll on your developer CD) for reading the configuration file during initial creation of End Entity (EE) token, although this is not required.
Your administrator can make some fields optional or mandatory in the Policy Wizard. They can see which fields are mandatory or required when they use the Policy Module API. Therefore, BT Trust Services recommends that you use the VeriSign Policy Module API. For information on Policy Module API documentation, contact your BT representative.
Note
Understanding Fundamental Assumptions

The following assumptions are fundamental to the browser emulation specification: The DN should be constructed according to the DN template given by the VSPM_CertSubjectDNTemplate function. This value is augmented by sophia.exe or sophialite.exe. Single key and dual key support is provided by including an ExtensionReq attribute in the PKCS#10 certificate request, which contains a KeyUsage extension. Clients use this method to request SubjectAltName values. You are responsible for publishing certificates and CRLs to LDAP. The AA server provides a mechanism, through an API, to add certificates and CRLs to an LDAP directory. Protocol message versions used in the communication between the client and Managed PKI are 1.0 for PKCS#10, and 1.5 for PKCS#7. During centralized key generation, PKCS#12 or PKCS#7 and PKCS#8 is used to import keyEnchipherment private keys generated by the Managed PKI Key Manager. Only RSA keys are certified. You cannot recertify a certified public key. Two valid certificates with the same DN and key usage may exist at the same time but only within 30 days of expiration of the older certificate. CA key update is done manually by out-of-band distribution of the new root CA public key to all PKI entities.
130
BT38-MPKI6-TRF-V1.1
Understanding End Entity Token Generation

An end entity is the person or device whose identifying information appears on a certificate. Using policy module, the client reads the policy configuration file created by the Managed PKI administrator for the PKI domain. The configuration file must be present for proper client installation. The configuration file contains the following values: The end entitys full DN except for the Common Name part (must be provided by end entity). (The policy module provides a DN template which describes how the DN must be constructed: CN = $common_name, OU = Engineering, O = VeriSign, Inc., C = US, so the $common_name variable must be substituted with the real common name.) AAs or CAs URL to use in PKI protocol The DN and alternative names of the CA issuing the certificate. Extensions required in certificate requests (keyUsage, subjectAlternativeName, and so on). Trusted public key (Root) in the form of self-signed certificates. The required regInfo (authentication info), together with its coding requirements. Whether keyEnchipherment keys can be generated on the client (that is, whether Managed PKI Key Management Service is implemented). The following items are not supported by the policy module or Managed PKI: LDAP addresses of company LDAP servers Minimal required and preferred key size in bits for key generation
Working with HTTP and MIME

Both the Automated Authentication and Managed PKI Key Manager servers receive an incoming message through a simple HTTP POST operation to a CGI program called sophialite.exe (for information about Sophialite, see Chapter 14, This section is intended for HTML authors using VHTML (Variable HTML) and Sophialite to:).
BT38-MPKI6-TRF-V1.1
131
The CA receives the incoming message through a simple HTTP POST operation to a CGI program called sophia.exe. The value of the Content-type variable should be application/x-www-form-url-encoded. The length of the message should be set by the Content-Length. The User-Agent variable is required and should have the value Browser Emulation. The body should be the name-value pairs, where the value is URL encoded according to RFC2396. An example of a certificate request:
POST /services/CompanyName/cgi-bin/sophia.exe HTTP/1.0\n User-Agent: Browser Emulation\n Content-type: application/x-www-form-urlencoded\n Content-Length: 603\n \n operation=C1LRAUserSubmit&form_file=%2E%2E%2Ffdf%2Fclient%2FuserEnrollMS%2Efdf&r emote_host=Browser+Emulation&public_key_format=pkcs10&common_name=Test&mail_emai l=test%5Fcompany%40com%2Ecom&public_key=MIIBTTCB%2BQIBADBNMQswCQYDVQQGEwJTRTEoMC YGA1UEChMfRW50ZWdyaXR5IFNvbHV0aW9ucyBDb3Jwb3JhdGlvbjEUMBIGA1UEAxMLVGVzdENsaWVudD EwXDANBgkqhkiG9w0BAQEFA%2FMANjLepcGf14tArnzQK4638je9hgV2rjQ9BGluHvi9shBITlbigJ4t EQ3UIwIDAQABoEcwRQYJKoZIhvcNAQkOMTgwNjAnBgNVHREEIDAegRx0aG9tYXNfY2FsZGVuaXVzQGhv dG1haWwuAANAAGIv5sz9ZP5jdSMpYyoRWtuwCM74nf5j36izH%2FGedu%2BfZsMN0ebiW8Ljl2NWpLBx G1WB5VMqaChA31BYU4SOog%3D%3D&challenge=1111\n
Messages returned back to the client is a list of name-value pairs embedded in a HTML file where the name-value pair is URL encoded according to RFC2396.
132
BT38-MPKI6-TRF-V1.1
It is up to the program performing browser emulation to parse the HTTP response and find the required name-value pairs.
Note
This is an example of a certificate response:

HTTP/1.1 200 OK\n Server: Netscape-Enterprise/3.0G\n Date: Thu, 23 Sep 1999 19:29:10 GMT\n Content-type: text/html\n Set-cookie: userEnrollMS=forward\n \n <HTML>\n <INPUT type=hidden name="error_status" value="6fff">\n <INPUT type=hidden name="certOrCrl" value="FNvbHV0awb3JhdGlvb jEUMBIGA1UEAxMLVG">\n </BODY></HTML>\n
End Entity Certificate Request Process for Managed PKI

This section describes the process for, and name/value pairs associated with, the process of requesting a certificate in Managed PKI. It includes information on the certificate request initiated by the users client application, the response from the AA or CA server, and process of picking up the certificate.
Requesting a Certificate
To request a certificate, a users client generates a key pair and certifies it. The client generates an RSA key pair and creates the corresponding PKCS #10 request.
BT38-MPKI6-TRF-V1.1
133
The client formats the request in name/value pairs. The following table describes all the name/value pairs sent by a client requesting a certificate.
Name operation Value Tag TEXT Mandatory / Optional mandatory Description Must be C1 LRAUserSubmit if enrollment request is sent directly to CA (at VeriSign). Must be AutoAuthOSUserSubmit if enrollment request is sent to RA (Local hosting). form_file remote_host public_key_form at public_key common_name CLEAR TEXT TEXT BASE64 TEXT mandatory mandatory mandatory mandatory optional Must be ../fdf/client/userEnrollMS.fdf Must be Browser Emulation Must be PKCS#10 The base64 encoded PKCS#10 Common name. Mandatory if mail_firstName and mail_lastName are not present Restrictions Must be the first name-value pair specified
Note: If policy file has UTF-8 option turned on when you customize the Local Hosting site kit, Value Tag is T61.
mail_firstName TEXT optional First name.
mail_lastName TEXT optional Last name.
mail_firstNamean d mail_lastName are mandatory if common_name is not supplied.
134
BT38-MPKI6-TRF-V1.1
Name challenge
Value Tag TEXT
Mandatory / Optional mandatory
Description This value is a challenge phrase supplied by the user during the registration process. A hash of this value is stored in the repository and is used to authenticate a revocation request.
Restrictions Max length is 32
Note: If policy file has

UTF-8 option turned on when you customize the Local Hosting site kit, Value Tag is T61. onsite_token country charEncoding charSet charFilter charFilterParam mail_email jobTitle employeeID PASSCODE TEXT CLEAR CLEAR CLEAR CLEAR EMAIL T61 T61 optional/man datory optional optional optional optional optional optional optional optional This value is placed in the title attribute in the DN. This value is placed in an Organizational Unit attribute in the DN This value is placed in an Organizational Unit attribute in the DN This value is placed in an Organizational Unit attribute in the DN Used for internationalization Used for internationalization Used for internationalization Used for internationalization Used for passcode authentication
mailStop
T61
optional
additional_field4
T61
optional
BT38-MPKI6-TRF-V1.1
135
Name additional_field5
Value Tag T61
Mandatory / Optional optional
Description This value is placed in an Organizational Unit attribute in the DN This value is placed in an Organizational Unit attribute in the DN
Restrictions
additional_field6
T61
optional
Using server authentication, the client sends the request to sophialite.exe or sophia.exe using the URI (Uniform Resource Identifier) specified in the configuration file over an SSL link. The name-value pairs are be sent in the enrollment and are retrieved from the Managed PKI Policy Module API VSPM_GetParameterCount() and VSPM_GetParameter(). All parameters with the VSPM_REQUIREMENT attribute set to VSPM_REQ_MANDATORY should be sent to the enrollment server. You can request the name-value pairs, the applicant's name as mail_firstName, and mail_lastName or common_name. The name value pairs are case sensitive.
Note
Response from Server

The client receives the reply within the same SSL connection. The reply is a set of name-value pairs, where the value-pair is URL encoded according to RFC2396. If
136
BT38-MPKI6-TRF-V1.1
successful, the reply contains a corresponding PKCS#7 (certificates and CRLs only) message. Otherwise the reply contains an error code.
Name error_status Value Tag TEXT Description Status code of the operation. error_status = 0x'3062' or 0x'1b59' indicates request is pending (manual authentication). error_status = 0x'0' or 0x'6fff' indicates successful response (Automated authentication). certOrCRL TEXT PKCS#7 that is first Base64 encoded, then URL encoded. Only present if certificate is approved Restrictions
If the certificate issuance is automatic, the client processes the PKCS #7 reply, or the user receives an e-mail from the Managed PKI CA containing the PIN that is used to retrieve the certificate.
Picking up the Certificate

To pick up an approved certificate, the user activates the clients choice for downloading the certificate from the AA or the CA and provides the PIN. The client creates name/value pairs containing the PIN and opens an SSL connection to the AA or the CA (server authentication only). The following table describes all the name-value pairs sent by a client to pick up a certificate.
Table 15-31 Name/Value pairs sent to pick up a certificate
Name operation form_file remote_host Value Tag TEXT CLEAR TEXT Mandatory/Option al mandatory mandatory mandatory Description Must be permenant (note spelling) Must be ../fdf/client/userGetIDMS.fdf Must be Browser emulation Restrictions
BT38-MPKI6-TRF-V1.1
137
Table 15-31 Name/Value pairs sent to pick up a certificate

Name secretCode Value Tag TEXT Mandatory/Option al mandatory Description value of PIN from confirmation e-mail message Restrictions
The client processes the PKCS #7 reply and the end entity is ready to use it.
End Entity Certificate Request Process for Managed PKI Key Management Service
Requesting a Certificate
A browser emulating client generates only a digitalSignature key. The keyEncipherment key pair is generated by the Managed PKI Key Management Service. The client generates an RSA key pair and creates the corresponding PKCS#10 request. The client formats the request in name-value pairs. The following table describes all the name-value pairs sent by a client requesting a certificate.
Name operation Value Tag TEXT Mandatory / Optional mandatory Description Must be AutoAuthOSUserSub mit. Use ../fdf/client/userEnroll DualMS.fdf for dual keys Use ../fdf/client/userEnroll EncMS.fdf for keyEncipherment key Use ../fdf/client/userEnroll MS.fdf for digitalSignature key Restrictions Must be the first name-value pair specified
form_file
CLEAR
mandatory
138
BT38-MPKI6-TRF-V1.1
Name remote_host public_key
Value Tag TEXT BASE64
Mandatory / Optional mandatory mandatory
Description Must be Browser emulation The base64 encoded PKCS#10 Must be NO This value is the challenge phrase supplied by the user during the registration process. A hash of this value is stored in the repository and is used to authenticate a revocation request.
Restrictions
Must be empty when ../fdf/client/userEnrollEnc MS.fdf is used.
authenticate challenge
TEXT TEXT
mandatory mandatory
Max length is 32
common_name TEXT optional/man datory Common name.

UTF-8 option turned on when you customize the Local Hosting site kit, Value Tag is T61.
Mandatory if mail_firstName and mail_lastName are not present
mail_firstName
TEXT
optional/man datory
First name.

BT38-MPKI6-TRF-V1.1
139
Name mail_lastName
Value Tag TEXT
Mandatory / Optional optional/man datory
Description Last name.
Restrictions mail_firstName and mail_lastName are mandatory if common_name is not supplied.

country charEncoding charSet charFilter mail_email jobTitle
TEXT CLEAR CLEAR CLEAR EMAIL T61
optional optional optional optional optional/man datory optional This value is placed in the Title attribute in the DN. This value is placed in an Organizational Unit attribute in the DN This value is placed in an Organizational Unit attribute in the DN This value is placed in an Organizational Unit attribute in the DN This value is placed in an Organizational Unit attribute in the DN This value is placed in an Organizational Unit attribute in the DN Used for internationalization Used for internationalization Used for internationalization
employeeID
T61
optional
mailStop
T61
optional
additional_field4
T61
optional
additional_field5
T61
optional
additional_field6
T61
optional
140
BT38-MPKI6-TRF-V1.1
The client posts the request to sophialite.exe in the Key Management Service local hosting site kit URL.
Note
Response from Server

The client receives the reply in the same SSL connection. The reply is a set of name-value pairs, where the value-pair is URL-encoded according to RFC2396 (standard for URI). If the certificate request is approved, the reply contains a corresponding PKCS#7 (certificates and CRLs only) message. Otherwise, the reply includes an error code.
Tip
The SSL connection is critical as the private key is sent in the reply.
Value Tag TEXT Description Status code of the operation. error_status = 0x'a104' indicates request is pending (manual authentication). error_status = 0x'0' or 0x'6fff' indicates successful response (Automated authentication). Restrictions
Name error_status
certOrCRL
TEXT
PKCS#7 that is first Base64 encoded, then Url encoded. This contains the certificate chain for the digitalSignature keyException: If operation is "PickupPKCS12", ignore this value
Only present if certificate is approved
pkcs8_line
TEXT
PKCS#8 that is first Base64 encoded, then Url encoded. This contains the keyEncipherment key
Only present if response is successfulException: It is not present if the operation is "permenant" (note spelling)
BT38-MPKI6-TRF-V1.1
141
Name pkcs7_line
Value Tag TEXT
Description PKCS#7 that is first Base64 encoded, then URL encoded. This contains the certificate chain for the keyEncipherment keyException:
Restrictions Only present if response is successfulException: It's not present if operation is permenant (note spelling).
pkcs12_pas sword
TEXT
Password to decrypt the private key during pick up of keyEncipherment key
Only present if request is pending
To get the PKCS#12 and its password for an encryption certificate, you have to manually change the key_format in the corresponding file from PKCS#8 to PKCS#12. Key Management Service version 3.5 and above supports PKCS#12 delivery method.
Note
Change the following file for the Key Management Service account for browser emulation: For htmldocs/client/userInstallEncMS.htm:
Content-Type:text/html
<HTML> <BODY> <INPUT type=hidden NAME=error_status VALUE="$$error_status$$"> <INPUT type=hidden NAME=pkcs7_line VALUE="$$pkcs7_line$$"> <INPUT type=hidden NAME=pkcs8_line VALUE="$$pkcs8_line$$"> </BODY> </HTML>
For htmldocs/client/userInstallMS.htm:
Content-Type:text/html <HTML> <BODY> <INPUT type=hidden NAME=error_status VALUE="$$error_status$$"> <INPUT type=hidden NAME=certOrCRL VALUE="$$certOrCRL$$"> </BODY> 142 BT38-MPKI6-TRF-V1.1
</HTML> For htmldocs/client/userInstallDualMS.htm: Content-Type:text/html <HTML> <BODY> <INPUT type=hidden NAME=error_status VALUE="$$error_status$$"> <INPUT type=hidden NAME=certOrCRL VALUE="$$certOrCRL$$"> <INPUT type=hidden NAME=pkcs7_line VALUE="$$pkcs7_line$$"> <INPUT type=hidden NAME=pkcs8_line VALUE="$$pkcs8_line$$"> </BODY> </HTML>
For htmldocs/error/KMpending.htm
Content-Type:text/html <HTML> <BODY> <INPUT type=hidden NAME=error_status VALUE="$$error_status$$"> <INPUT type=hidden NAME=pkcs12_password VALUE="$$pkcs12_password$$"> </BODY> </HTML>
Enrollment Operation Input:

POST /cgi-bin/sophialite.exe HTTP/1.0 User-Agent: Browser Emulation Content-Type: application/x-www-form-urlencoded Content-Length: 275 query operation=AutoAuthOSUserSubmit&authenticate=NO&form_file=..%2Ffdf%2Fclient%2FuserEnr ollEncMS.fdf&remote_host=Browser+Emulation&public_key=&mail_firstName=1809&mail_last Name=1209&mail_email=approve@verisign.com&jobTitle=&employeeID=1234&mailStop=&locali ty=&state=&country=&challenge=1
Sample Enrollment Response from Server after making the suggested change to the Local Hosting Site kit:
<HTML> <BODY> <INPUT type=hidden NAME=error_status VALUE="6fff"> <INPUT type=hidden NAME=pkcs7_line VALUE="MIIHcAYJKoZIhvcNAQcCoIIHYTCAAgEBMQAw BT38-MPKI6-TRF-V1.1 143
CwYJKoZIhvcNAQcBoIAwggP3MIIDoaA3uAc4u7gsVcBVOaJeL4ijMA0GCSqGSIb3DQEBBAUAMEMxETAPBgNVBAoTCFZlcmlTa WduMS4wLAYDVQQLEyVWZXJpU2lnbiBDbGFzcyAyIE9uU2l0ZSBJbmRpdmlkdWFsIENBMB4XDTAyMTIxMTAwMDAwMFoXDTAyMT IxODIzNTk1OVowgcUxETAPBgNVBAoUCEdhcnJpc29uMRMwEQYDVQQLFApLZXlNYW5hZ2VyMUYwRAYDVQQLdmVyaXNpZ24uY29 tL3JlcG9zaXRvcnkvQ1BTIEluY29ycC4gYnkgUmVmLixMSUFCLkxURChjKTk5MRowGAYDVQQLFBFFbXBsb3llZUlEIC0gMTIz NDESMBAGA1UEAxMJMTQzNCAxMjEwMSMwIQYJKoZIhvcNAQkBFhRhcHByb3ZlQHZlcmlzaWduLmNvbTCBnzANBgkqhkiG9w0BA QEFAAOBjQAwgYkCgYEAvqLloqs58go7FpNMbDL5tOcEXDE7PeHCEam0rFbHGcgCpTslS88e5jLgvMqtxhRdAmrmh+krCv5QbH 2FZy9IOGD/PcZvrEL7oP80NJ38J06URB5HUHBEqk8rexSZiqkRhMF3H3iNeHVUEq5msJwcJl5LZC45ru8GX4/lSC/ZizsCAwE AAaOCAagwggGkMAkGA1UdEwQCMAAwggEkBgNVHSAEggEbMIIBFzCCARMGC2CGSAGG+EUBBwEGMIIBAjArBggrBgEFBQcCARYf aHR0cHM6Ly93d3cudmVyaXNpZ24uY29tL3JwYS1rcjCB0gYIKwYBBQUHAgIwgcUagcJOT1RJQ0U6IFByaXZhdGUga2V5IG1he SBiZSByZWNvdmVyZWQgYnkgVmVyaVNpZ24ncyBjdXN0b21lciB3aG8gbWF5IGJlIGFibGUgdG8gZGVjcnlwdCBtZXNzYWdlcy B5b3Ugc2VuZCB0byBjZXJ0aWZpY2F0ZSBob2xkZXIuICBVc2UgaXMgc3ViamVjdCB0byB0ZXJtcyBhdCBodHRwczovL3d3dy5 2ZXJpc2lnbi5jb20vcnBhLWtyIChjKTk5LjALBgNVHQ8EBAMCBSAwEQYJYIZIAYb4QgEBBAQDAgeAME8GA1UdHwRIMEYwRKBC Ib3DQEBBAUAA0EAAQLm0P5Rdq7QgQmZl2IVZXypuiolE5mxbSXN32sQNA35i9kBfF9ds8LKx0zQ8Fs9e0BKw5FSW19P6jLrKR 3UizCCA0YwggKvoAMCAQICEAJyLlkVWyrrnlQeLtXcRJQwDQYJKoZIhvcNAQEFgNVBAYTAlVTMRcwFQYDVQQKEw5WZXJpU2ln biwgSW5jLjFBMD8GA1UECxM4Q2xhc3MgMiBURVNUIFB1YmxpYyBQcmltYXJ5IENlcnRpZmljYXRpb24gQXV0aG9yaXR5IC0gR zIxQzBBBgNVBAsTOlRlcm1zIG9mIHVzZSBhdCBodHRwczovL3d3dy52ZXJpc2lnbi5jb20vY3BzL3Rlc3RjYS8gKGMpMDIxHz AdBgNVBAsTFlZlcmlTaWduIFRydXN0IE5ldHdvcmsxHzAdBgNVBAsTFkZvciBUZXN0IFB1cnBvc2VzIE9ubHkwHhcNMDIwNzE yMDAwMDAwWhcNMDcwNzExMjM1OTU5WjBDMREwDwYDVQQKEwhWZXJpU2lnbjEuMCwGA1UECxMlVmVyaVNpZ24gQ2xhc3MgMiBP blNpdGUgSW5kaXZpZHVhbCBDQTBcMA0GCSqGSIb3DQEBAQUAA0sAMEgCQQDBxzQcrg+TVGE2erKVwdCYECWHOICDqj/oHiMlu BVeF3oNIEYZAsfYohYmkkOoGP/qfCecH76QoXTONQ8aX1AgMBAAGjgdAwgc0wDwYDVR0TBAgwBgEB/wIBADBLBgNVHSAERDBC MEAGCmCGSAGG+EUBBxUwMjAwBggrBgEFBQcCARYkaHR0cHM6Ly93d3cudmVyaXNpZ24uY29tL2Nwcy90ZXN0Y2EvME0GA1UdH wRGMEQwQqBAoD6GPGh0dHA6Ly9waWxvdG9uc2l0ZWNybC52ZXJpc2lnbi5jb20vT2ZmbGluZUNBL3Rlc3RwY2EyLWcyLmNybD ALBgNVHQ8EBAMCAQYwEQYJYIZIAYb4QgEBBAQDAgEGMA0GCSqGSIb3DQEBBQUAA4GBAG3RSVMxLPVhRjZApGW5ZH9x11kCbpj UCFC3OmsKi1UFPOyy515bZjawM43TjTr/BK8UO/PQtGjHWRClq3dPInD9WoQt64lQS5y181jepq696/oJDki549p9tUjzdgai +HQl6cIi8AsBBq/YueKgDGiveLIJmIza+EeC4GLzgn0MAAAxAAAA"> <INPUT type=hidden NAME=pkcs8_line VALUE="MIICeAIBADANBgkqhkiG9w0BAQEFAASCAmIw ggJeAgEAAoGBAL6i5aKrOfIKOxaTTGwy+bTnBFwxOz3hwhGptKxWxxnIAqU7JUvPHuYy4LzKrcYUXQJq5ofpKwr+UGx9hWcvS Dhg/z3Gb6xC+6D/NDSd/CdOlEQeR1BwRKpPK3sUmYqpEYTBdx94jXh1VBKuZrCcHCZeS2QuOa7vBl+P5Ugv2Ys7AgMBAAECgY EAigbx0zy8gMXtkGPoMnMaH2Qg4Qt4RE7gL9+7BAj0sXMCj1XqpB/71FrEI41wEnoN+cEi1wb49kW6P0MGwvYWCBQxJUU9KLc +nVYoavd3SJ8zcbluawfVamtkOhlV0F2fKJM4cXFArTi9vKlXka86wglFyRJ/yh7GH1+gECQQDeqkNw4ul3W+T/Z7KecldHtY 3cJwxZrr/LK9AVRSPdSHTskcDT3RP6HzjvA3AsJhJO0VJrkQBye0dQeMKYwo7AkEA2y0d6DCplm1WD6lefIr7rXMK1Rlhxkhe q96XK7+dekqxwsQICkCwPz5MlYWBm62XKPtGFtgjfdgsDG7pzAQJAMMnt7RZLQbQJAU2ffchgB35ojwyfUCdSLxpyhbaYnSGc n944YSlPuxKeCuhxuv7231T1Yaeljx7Hrdl5/hSlcQJBAIguMDbkhXqB1MdGZQU3razZE0Q/doKO0YIEUqYszTrid1CK9DoHF bCer/Q5aTBnxYrdZBxD8uB4AuBFV1kTMAECQQCnTP+JsMCv8tnMPuroASdn4p0SoabytFVfgajeTQZDUrn+vg/NVQuuSurQpm pe/yoxraaw noCAg/cvGuUU65dc"> </BODY> </HTML>
144
BT38-MPKI6-TRF-V1.1
Pickup Certificate for digitalSignature Key

The following table describes the name-value pairs sent by a client to pick up the certificate for digitalSignature key.
Name operation form_file remote_host secretCode Value Tag TEXT CLEAR TEXT TEXT Mandatory / Optional mandatory mandatory mandatory mandatory Description Must be permenant (note spelling) Must be ../fdf/client/userGetIDMS.fdf Must be Browser Emulation Value of PIN from confirmation e-mail message for the digitalSignature key Restrictions
Pick up keyEncipherment Key and its Certificate

The following table describes all of the name-value pairs send by a client to pick up the keyEncipherment key and its certificate.
Name operation form_file remote_host kr_refnum Value Tag TEXT CLEAR TEXT TEXT Mandatory/ Optional mandatory mandatory mandatory mandatory Description Must be PickupPKCS#12 Must be ../fdf/client/userGetEncMS.fdf Must be Browser Emulation Value of PIN from confirmation e-mail message for the keyEncipherment key Value of "pkcs12_password" in the server response for the enrollment request Restriction s
pkcs12_password
TEXT
mandatory
BT38-MPKI6-TRF-V1.1
145
Renew Certificate for digitalSignature key

The following table describes all the name-value pairs sent by a client to pick up the certificate for digitalSignature key.
Name operation form_file remote_host getMethod orig_cert_serial orig_cert_issuer dn pkcsInformation Value Tag TEXT CLEAR TEXT TEXT TEXT TEXT Mandatory/ Optional mandatory mandatory mandatory mandatory mandatory mandatory Description Must be userRenewal Must be ../fdf/client/ userRenewalMS.fdf Must be Browser Emulation Must be PKCS#7 Certificate serial of the to be renewed certificate Certificate issuer DN of the to be renewed certificate PKCS#7 signed message in base64 format Must be Renew Digital ID The base64 encoded PKCS#10 Restrictions
TEXT
mandatory
detachedMesg public_key BASE64
mandatory mandatory
Renew keyEncipherment Key and its Certificate

The following table describes all the name-value pairs sent by a client to pick up the keyEncipherment key and its certificate.
Name operation form_file Value Tag TEXT CLEAR Mandatory/ Optional mandatory mandatory Description Must be userRenewal Must be ../fdf/client/userRenewalEn cMS.fdf Restrictions
146
BT38-MPKI6-TRF-V1.1
Name remote_host getMethod orig_cert_serial orig_cert_issuerd n pkcsInformation detachedMesg public_key
Value Tag TEXT TEXT TEXT TEXT TEXT
Mandatory/ Optional mandatory mandatory mandatory mandatory mandatory mandatory
Description Must be Browser Emulation Must be PKCS#7 Certificate serial of the to be renewed certificate Certificate issuer DN of the to be renewed certificate PKCS#7 signed message in base64 format Must be Renew Digital ID The base64 encoded PKCS#10
Restrictions
BASE64
mandatory
Must be empty for KeyEncipherm ent key
BT38-MPKI6-TRF-V1.1
147
148
BT38-MPKI6-TRF-V1.1
APPENDIX A
About Certificate-Based Access Control

AxidnepA
This appendix provides foundation knowledge about access control in general and certificate-based access control in particular. It also provides examples of access control solutions and step-by-step instructions for how to implement them. The chapter contains the following sections: Overview on page 149 Certificates as a Basis for Access Control on page 150 Access Control Architectural Models on page 153 Microsoft Examples: Internet Information Server (IIS) Solutions on page 156 (includes step-by-step instructions) Netscape Examples: Web Server Solutions on page 176 Implementation Guidelines for Managed PKI Web Access Control on page 188
Overview
Enterprises have traditionally used password-based authentication systems to restrict resource access to authorized users. Authorized users may be a small group such as the enterprises employees or business partners, or a large group such as the general public. Password-based solutions have also been used to secure Web resources. As technology and programming have become more sophisticated and complex, however, password-based authentication systems have not proven themselves able to provide the required level of access-control protection.
Because of this, systems protected only by password-based solutions are highly vulnerable to security attacks. Certificate-based authentication systems provide an alternative to traditional password-based systems. Digital IDs can be used either as a replacement for passwords, or in conjunction with them for added security. Certificate-based authentication systems offer greater security, even if not used in conjunction with a password-based solution. This is because for a user to establish his or her identity in a two-factor authentication system, he or she must prove possession of a token (the private key) and knowledge of a passphrase. The passphrase that a user supplies is typically a PIN (Personal Identification Number) that unlocks a smart card, or is a password to decrypt a private key.
Certificates as a Basis for Access Control

An enterprise can use subscriber certificates to secure access to its resources for its employees (intranets), business partners (extranets), and the public (Internet). In a certificate-based Web access control system, subscribers must present their certificates when they access a Web server from their browser. The access control system employs a cryptographic protocol (Secure Sockets Layer (SSL)) to establish a subscribers identity (authenticate the subscriber), determine the subscribers access rights (authorization), and then grant or deny access appropriately. This section discusses Subscriber Authentication on page 150 Designing a Certificate-Based Access Control System on page 151 Certificate Lifecycle for Subscriber Certificates in Browsers on page 152 Denial of Access and Revocation Checking on page 152
Subscriber Authentication
When a Web browser accesses an SSL-enabled Web server, the browser always unilaterally authenticates the server.
150
BT38-MPKI6-TRF-V1.1
Appendix A About Certificate-Based Access Control
The authentication of the Web server is based on the servers SSL certificate, the servers ability to prove that it possesses the private key corresponding to its certified public key, the notion of trust (root keys) in the browser, certificate revocation information, and other policy factors. During the SSL handshake protocol, the Web server can optionally authenticate the subscriber who is trying to access the resource through the Web browser. The authentication of the subscriber to the Web server results in a mutual authentication of the Web server and Web browser. The Web server uses the subscriber certificate, the subscribers ability to prove that she possesses the private key corresponding to her certified public key, the servers trust policy, revocation data, and other policy rules to determine whether to trust the identity of the subscriber.
Designing a Certificate-Based Access Control System

An enterprise has a number of design options among which to choose for its access control system. The decision of which design to choose depends on the requirements of the access control system, the operating system, the Web server vendor, and the complexity of the system. An enterprise can leverage native Web server features to enforce access control, or it can parse the information within a certificate and write custom code to derive access control privileges from a database based on certificate field values. The quickest way to deploy an access control system is to permit access only if a subscriber can present a valid certificate. In this case, the Web server is configured to trust certain roots, and only a subscriber who can present a valid certificate signed by a trusted root can gain access to resources. Both Microsoft and Netscape Web servers have native support for this approach. In a slightly more complicated implementation, an enterprise can create Windows accounts for legitimate users, use access control lists (ACLs) to associate resources with users on a NTFS partition, and leverage Microsoft IIS built-in features to map subscriber certificates to Windows accounts to enforce access control. Netscape provides a tight integration between its Web server and LDAP directory server. An enterprise defines ACLs for resources within Netscape Web server, sets up user accounts in the Netscape LDAP directory, and customizes Netscapes
certificate mapping API to map subscriber certificates to LDAP accounts in order to determine and enforce access rights. An enterprise can also store account information and access privileges in a relational database, and write custom code to look up subscribers access privileges in the database based on their certificates. Access Control Architectural Models on page 153 discusses a variety of access control architectures.
Certificate Lifecycle for Subscriber Certificates in Browsers

Before a subscriber can access a resource through a certificate-based Web access control system, he or she must have a subscriber certificate installed in his or her browser. VeriSign Managed PKI makes it easy for a person to enroll for a subscriber certificate, or Digital ID, and to manage the Digital ID during its lifecycle. Lifecycle management processes include Digital ID enrollment, pickup, renewal, and revocation. Lifecycle management functions are discussed in detail in Access Control Architectural Models on page 153.
Denial of Access and Revocation Checking

An access control system must address how the access can be denied to a previously authorized user. Certificate-based systems offer two methods to take away access. The methods are not mutually exclusive and can be used together, if desired. In the first method, the subscribers certificate is revoked. The Web server is configured to check revocation information to ensure that the binding between a subscribers identity and his or her private key is still valid before granting access. The Web server can use certificate revocation lists (CRLs) to determine whether a particular certificate has been revoked. VeriSign Managed PKI supports CRLs, and it provides a plug-in for Microsoft or Netscape Web servers to perform revocation checking. See Go Secure! for Web Applications Installation and Configuration Guide for more details. The second method applies when the access control system uses a database to store account and access privileges. To deny access, simply turn off the subscribers privileges in the database.
In the Netscape LDAP case, for example, remove the subscribers account information. If an enterprise is using a relational database to store account information, either remove the subscribers account or turn off the subscribers privilege by setting a flag in the database. If an enterprise is using Microsoft IIS to map certificates to Windows accounts, it can disable the subscribers account. This issue is discussed in Access Control Architectural Models on page 153.
Access Control Architectural Models

This section discusses different architectural models that an enterprise can use to implement an access control solution. The material is this section is intended to be theoretical. The Microsoft and Netscape examples at the end of this chapter provide detailed step-by-step instructions on implementing each of these access control models. The instructions are explicit, however, the implementations are still examples and many variations are possible. It is important to customize your enterprises implementation to suit your identified needs and circumstances.
Just Trust the Root

Just Trust the Root is the simplest access control model and the fastest way an enterprise can implement a certificate-based access control solution. In this model, the decision to grant a subscriber access to a resource is based solely on whether the subscriber can present a certificate that is signed by a trusted root. During the SSL handshake and mutual subscriber authentication, the Web server attempts to validate the subscriber certificate. If the certificate is signed by a root that is trusted by the Web server and meets other verification criteria (for example, it is not expired and the certificate chain is valid) the Web server allows the subscriber to access the resource. This model grants the same level of access control privileges to all subscribers. It cannot distinguish among subscribers or grant different access accordingly.
BT38-MPKI6-TRF-V1.1
153
Because the decision to grant or deny access is based on the root signature, this model works best with private Managed PKI hierarchies. This model can also work with public hierarchies on some servers. For example, with IIS, the server needs additional configuration to use advanced certificate mapping so that only public Managed PKI certificates that have a specific value in a certain organization field in the subject information are accepted. It is critical to configure the Web server to check the revocation information and to revoke a subscribers certificate when he or she should no longer be allowed to access a resource. Keep in mind that there is an interval during which the access control system might violate its integrity rules. This interval is the time between when a person should no longer be permitted to access a resource and when the persons certificate is revoked and the revocation information is updated. You can use this method in conjunction with another level of security (application-level passwords) to give individuals specific access privileges. This is a useful implementation for enterprises that have an existing security infrastructure, and that want to add certificates as an added, more-secure layer of access control in addition to the existing method.
Map to User Accounts

This model exploits native Web server features to map a subscriber certificate to an operating system user account. The mapped account is used to determine the access privileges of a subscriber: these privileges are assigned using the operating system. For example, NTFS lets a system administrator associate an access control list (ACL) with a resource. The ACL precisely defines the list of users and the actions rights that they are permitted, or forbidden, to perform on a resource. When a subscriber attempts to access a resource through a Web server, the server maps the subscribers certificate to a user account and grants access to a resource only if such access is allowed by the ACL associated with the resource. The access control granularity of this model depends on how many user accounts are involved in the mapping. At one extreme, all subscribers can be mapped to only one account. At the other extreme, each subscriber can have a distinct account. Between these two extremes, there might be one distinct account for each distinct subset of subscribers.
154
BT38-MPKI6-TRF-V1.1
An enterprise can, for example, create one distinct account for each of its business partner companies and issue a certificate for each designated employee of a business partner. Certificates could have a field that distinguishes business partners from each other, such as an organizational unit field. The enterprise can then configure its Web server and map all the designated employees of a business partner to the appropriate account configuration for that partner. An organization thus imposes its access control policies by carefully setting up access privileges for each business partner account. If the enterprise needs to support different access privileges for employees within a particular business partner, it can configure more than one account for the partner and use another field in the certificate, such as the organizational unit, to carry out the appropriate mappings. Although this is an example of an extranet case, mapping certificates to user accounts is not limited to extranets. An enterprise can use the same techniques to control access for its internal employees. For example, it can configure an access control solution that determines access based on the department for which an employee works. To revoke the access privileges of a previously authorized person, either the certificate can be revoked, or the account used for certificate mapping can be disabled. The latter option works only if the person has a dedicated account for mapping. If the person shares the mapped account with other subscribers, certificate revocation is the only option. In any case, it is always recommended to deny access at every point at which denial is possible.
Map to User Accounts In LDAP

In this model, an LDAP directory service maintains a list of user accounts and group information, and the Web server associates an ACL with a resource. The ACL specifies the rights that a user or group is permitted (or denied) for a resource. When a subscriber presents a certificate, the Web server maps the certificate into an LDAP entry and determines the user account. The Web server then uses the account information and the resources ACL to determine whether the subscriber should be granted the requested access to the resource.
BT38-MPKI6-TRF-V1.1
155
For example, Netscape Web servers use a certificate mapping API to control the mapping of subscriber certificates to user accounts. An enterprise might customize this API and use the common name field of a certificate to assign a unique account for every subscriber, or use the organization field to map many subscriber certificates to one account. Netscape provides a tight integration between its Web servers and LDAP directory and an end-to-end access control solution based on this model. As with the previous model, an enterprise can use several methods to remove a subscribers access privileges. It can revoke the persons certificate and perform revocation checking with the Web server, disable the persons account information from the LDAP directory, or implement both methods together. If the access control system maps more than one subscriber to one account, however, the second method does not work and certificate revocation is the only practical method for denying access.
Map to Database
This model is similar to the LDAP model, except that account information is kept in a non-LDAP compliant database. The overall decision flow is the same. A subscriber presents a certificate in order to access a resource; the access control system authenticates the subscriber and then uses the certificate as an index into the database to determine account information and access rights. Mapping a certificate into a database entry may involve more custom programming than the LDAP case, because Web server vendors do not generally provide end-to-end solutions. To remove the access privileges of a user from the system, the subscribers certificate can be revoked, or the subscribers account information in the database can be disabled, or both.
Microsoft Examples: Internet Information Server (IIS) Solutions

This section describes in detail how you can use Microsoft technology to implement the access control solutions described above.
156
BT38-MPKI6-TRF-V1.1
Preparing IIS for Access Control

This section provides instruction for performing tasks common to many of the access control models described earlier. Keep in mind that although these instructions are explicit, they still describe an example implementation and many variations are possible. Your implementation must reflect your enterprises needs and circumstances. Installing a Private CA on IIS with Windows 2000 Follow these steps to install a Certification Authority certificate.
1 2
First, obtain the CA that you want to trust. Create a certificates management console to manage the certificates for the computer you are working on, as follows:
a b c d e f g
From the Start menu, click Run. The Run dialog box appears. Type mmc and choose OK. From the Console menu, click Add/Remove Snap-in. In the next dialog box, click Certificates, and then choose Add. Click Computer account, then choose Next. Click Local computer, then choose Finish. Choose Close, and then choose OK. The Certificates directory now appears in the left pane of the console. From the Console menu, click Save As. In the File name text box, type Certificates, and then choose Save.
h i 3
In the console, expand the Certificates node. Then expand Trusted Root Certification Authorities.
BT38-MPKI6-TRF-V1.1
157
Right-click the Certificates folder, point to All Tasks, and then click Import, as shown below.
Figure A-1 Importing the CA certificate

5 6
The Certificate Import Wizard starts. Choose Next. Choose Browse to select the CA certificate you want to import. Then choose Next. Select Place all certificates in the following store, and choose Browse and select the Trusted Root Certification Authority store. Then choose Next to store the CA certificate. Read all the information in the Completing the Certificate Import Wizard window, and then choose Finish.
The CA certificate is now installed. Verify this by scrolling through the certificates list in the right pane and locating the certificate you just installed. Installing a Server Certificate Refer to your supplier for instructions on installing server certificates.
158
BT38-MPKI6-TRF-V1.1
Requiring Subscriber Certificates To require users to present their certificates when they access an SSL-enabled Web server, you must first configure IIS to use the SSL protocol and then instruct IIS to require subscriber certificates. IIS is typically configured to use the Private Communication Technology (PCT) protocol with browsers that support PCT, such as IE.
To view the default protocol (IE 4.0)
If you have IE 4.0, follow these instructions to view the default protocol:
1 2 3
Make sure SSL is enabled on the Web server. Connect your IE browser to IIS using the https protocol. Double-click the lock symbol that appears at the bottom of the browser window. In the Properties dialog box, select the Security protocol field.
Figure A-2 Connection properties for a secure channel
If the value of Properties field is PCT instead of SSL or TLS (TLS or Transport Layer Security is the latest version of SSL), you must edit the Windows registry, as explained in To change the default setting: on page 160.
BT38-MPKI6-TRF-V1.1
159
Note It is possible to configure IE to force IIS to use SSL instead of PCT. In that case, the Security protocol field displays SSL even though the servers default protocol is still PCT. Unless you have specifically configured IE to use SSL, you can assume the Security protocol field shows IIS default security protocol field.
To view the default protocol (IE 5.0)
If you have IE 5.0, follow these instructions to view the default protocol:
1 2 3
Make sure SSL is enabled on the Web server. Connect your IE browser to IIS using the https protocol. Place the cursor on any text on the Web page (avoid graphics or links). Right-click Properties. The protocol version appears in a dialog box.
To change the default setting:

1 2
From the Start menu, click Run. The Run dialog box appears. Type regedit and click OK. The Registry Editor starts.
Using Registry Editor incorrectly can cause serious problems that may require you to reinstall Windows. Neither VeriSign nor Microsoft can guarantee that problems resulting from the incorrect use of Registry Editor can be solved. Use Registry Editor at your own risk.
CAUTION 3
Open the HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\ Control\SecurityProviders\SCHANNEL\Protocols\PCT 1.0 subkey and select Server. From the Edit menu, select New, and then select Binary Value. A new value appears in the right-side pane. If necessary, right-click the new item and select Rename. Type Enabled and press Enter. Right-click the enabled item and select Modify. The Edit Binary Value dialog appears. Type 00000000 (eight zeros) and click OK.
160
BT38-MPKI6-TRF-V1.1
8 9
Select Exit from the Registry menu bar to close the Registry Editor. Reboot the computer. This change will take effect the next time you start Windows.
To configure IIS to require subscriber certificates:
In this procedure, you instruct IIS to require subscriber certificates. You can use these steps to protect your entire Web site, individual directories, or individual files.
1 2
Make sure SSL is enabled on the Web server. Bring up Microsoft Management Console (MMC), select your Web site, right-click and select Properties from the pop-up menu. Select the Directory Security tab (Figure A-3)..
Figure A-3 Web site properties

3
Click the Edit button under Secure Communications.
BT38-MPKI6-TRF-V1.1
161
In the Secure Communications dialog box, check the Require Secure Channel when accessing this resource box, and select Require Subscriber Certificates (Figure A-4)..
Figure A-4 Secure Communications dialog box

5
Save your changes and restart IIS.
Just Trust the Root (IIS)

As discussed in Just Trust the Root on page 153, this model is the quickest way to implement an access control system. These instructions assume that you have a private root CA, but you can use a public CA if you add the rules described in Map to User Accounts on page 154. You need two rules, the first matched against the VeriSign Class 2 PCA Root granting access to any certificate in which the subject organization field matches that of your Managed PKI account. The second rule is a wildcard rule refusing access to all other certificates.
To implement Just Trust the Root for IIS
1 2
Make sure SSL is enabled on the IIS server. Install the private CA root in the Web Server. See Installing a Private CA on IIS with Windows 2000 on page 157 for instructions.
BT38-MPKI6-TRF-V1.1
162
Configure the list of trusted roots on IIS. Enable the Managed PKI private root and disable all the other roots. If you leave a public root enabled, a subscriber with a certificate issued by a root other than your private root can access the Web resources. Require subscriber certificate authentication by following the instructions in Requiring Subscriber Certificates on page 159. Install the VeriSign Managed PKI Certificate Validation Module (CVM) on the Web server. See Managed PKI Certificate Validation and Parsing Guide for instructions.
Recommended Testing Use the following test scenario to test the basic functionality of the access control system.
1
Use Managed PKI to issue a subscriber (browser) certificate for yourself under your private hierarchy. Use the certificate to access a resource on the Web server. Access Managed PKI to revoke your certificate and update the CRL. You should no longer be able to access the Web server. Try to access the Web server using a certificate issued by a root other than your private root. Access should be denied. A good test would be to use a certificate issued by a public root you disabled when you configured the list of trusted roots.
Map to User Accounts (IIS)

You can leverage built-in IIS features to control access to resources by mapping subscriber certificates into Windows accounts. Even if a subscriber is impersonated on the Web server, Windows grants access to a resource only if the impersonation results in a Windows account that has appropriate access rights to the resource. To implement an access control system based on certificate mapping, the Web servers resources must reside on an NTFS partition. NTFS supports ACLs, which let you associate a list of users and their access privileges with a resource.
BT38-MPKI6-TRF-V1.1
163
The Web server must first authenticate subscriber certificates before it can map them to accounts. If you are using a private Managed PKI hierarchy, you must import the private root into IIS, as described in Just Trust the Root (IIS) on page 162. Regardless of the type of hierarchy (private or public), it is recommended to configure the list of roots trusted by IIS and remove the unnecessary public roots.
Note
You can use the subscriber certificate mapping feature in two ways. First, you can configure IIS to handle each certificate in its entirety and map a user to a Windows account if the full content of a users certificate matches a predetermined certificate. Second, or in conjunction with the first method, you can specify matching rules and configure the certificate mapping based on specific certificate fields, such as the users organization name. These two methods are described in the following subsections. Map the Certificate to a User Account You can configure IIS to match a subscriber certificate to a list of internally-defined certificates and to map to a Windows account if a match is found. When you configure IIS to map certificates individually, you must specifically define a mapping for each user who needs to access the Web server. IIS documentation uses the term one-to-one mapping for this method of subscriber certificate mapping. Contrary to what you might think it means, one-to-one mapping does not necessarily imply that you must map each subscriber certificate to a distinct account. You can map multiple certificates to a single account, but you must define a one-to-one mapping for each subscriber certificate. The need to define a mapping for each user, however, poses a scalability issue. Another issue with the one-to-one mapping approach is that you must have a text (ASCII) copy of the subscribers certificate during configuration. This may not always be possible.
164
BT38-MPKI6-TRF-V1.1
You can use Active Server Pages to create a script for extracting subscriber certificate information from the users HTTP request header. See the Active Server Pages documentation for more information. Follow these instructions to configure your access control system:
1
Determine the number of accounts needed for mapping. Refer to Map to User Accounts on page 154 for more information. Configure all the required accounts on your system. If each certificate holder already has an account (for example, they are employees) you can use the existing accounts.
Determine the resources (files and directories) you want to restrict and assign an appropriate ACL to each resource. The resources must reside on an NTFS partition. Follow the instructions in Just Trust the Root (IIS) on page 162 to configure the list of roots trusted by IIS. Bring up the Microsoft Management Console (MMC). Select your Web site. Right-click and select Properties from the pop-up menu. Select the Directory Security tab from the Properties dialog box. Click the Edit button under Secure Communications. In the Secure Communications dialog box, check the Require Secure Channel when accessing this resource box, select Require Subscriber
BT38-MPKI6-TRF-V1.1
165
Certificates, and check the Enable Subscriber Certificate Mapping box, as shown.
Figure A-5 Enabling subscriber certificate mapping in the Secure Communications dialog box
166
BT38-MPKI6-TRF-V1.1
Click the Edit button in the Secure Communications dialog box. The Account Mappings dialog box appears (Figure A-6). Select the Basic tab.
Figure A-6 Account Mappings dialog box

7
In the Account Mappings dialog box, click the Add button to define a new mapping. You must first designate the certificate used for mapping. You must have a text (ASCII) copy of the subscribers certificate. Click the Open button to open the Map to Account dialog box.
BT38-MPKI6-TRF-V1.1
167
Specify the account that should be used for mapping in the Map to Account dialog box (Figure A-7).
Figure A-7 Choosing a certificate for mapping

10
IIS displays the new mapping in the Account Mappings dialog box (Figure A-8). Define any additional mappings. Save the changes.
Figure A-8 Choosing an account for mapping

11
Determine how you intend to handle revocation of access privileges. Install the VeriSign Managed PKI Certificate Validation Module (CVM) on the Web server if required.
168
BT38-MPKI6-TRF-V1.1
Figure A-9 Account Mappings dialog box with a new mapping defined
1 2
Use Managed PKI to issue a subscriber (browser) certificate for yourself. Map your Digital ID to an account that has access privileges to a resource. Use the Digital ID to access that resource on the Web server. Use a Digital ID that is not mapped to any account to access the resource. Access should be denied. If you have installed the CVM, access Managed PKI to revoke your mapped Digital ID and update the CRL (in most cases, you have to wait 24 hours). You should no longer be able to access the Web server.
Map the Certificate to a User Account Based on Certificate Fields (IIS) A more practical way to map certificates to accounts is to configure IIS to match certificates based on their fields.
BT38-MPKI6-TRF-V1.1
169
For example, you can set up IIS to map all certificates whose organization field is businessPartner1 to the businessPartner1 account, and map all certificates whose organization field is businessPartner2 to businessPartner2 account. You can also use it to mimic the just trust the root configuration of private hierarchies. The many-to-one mapping (a term used in IIS documentation) eliminates both the need to have access to users certificates during the configuration phase and the need to configure a mapping for each user. As an Managed PKI administrator, you must carefully design the content of end-user certificates if you are planning to use certificate fields for mapping. The Policy Wizard lets you define additional fields in end-user enrollment pages and to specify the fields you want to appear in certificates. You can run the Policy Wizard multiple times. If you are using Local Hosting or Automated Administration, you may have to make changes to the certificate lifecycle Web pages.
Note
IIS formats the information within subscriber certificates into arrangements of fields and subfields. Field names represent general categories of information and consist of subfields, which contain specific identification information. IIS supported field names are Subject, Issuer, and Serial Number. The following list describes the basic subfields contained in a certificate: Organization (O) Preferably International Organization for Standardization (ISO)-registered top-level enterprise or company name. Organizational Unit (OU) A department within an enterprise, such as Marketing. Common Name (CN) The domain name of the server, for example, www.microsoft.com. Country (C) Two letter ISO country designation (for example, AU, FR, UK, US) State/Province (S) Full name of the state or province with no abbreviation (for example, Washington, Alberta, California). Locality (L) The full name of the city in which your organization is located, such as Redmond or Toronto.
Initials (I). Given Name (GN). Title (T). Follow these instructions to configure your access control system:
1
Establish the certificate mapping rules you intend to use. Determine the certificate fields required to support the mapping rules. Run the Policy Wizard and customize the end-user enrollment pages accordingly. Specify the number of accounts needed for mapping. Refer to Map to User Accounts on page 154 for more information. Configure all the required accounts on your system. Determine the resources (files and directories) you want to restrict and assign an appropriate ACL to each resource. The resources must reside on a NTFS partition. Follow the instructions in Just Trust the Root (IIS) on page 162 to configure the list of roots trusted by IIS. Start MMC and select your Web site. Right-click, and select Properties from the pop-up menu. Select the Directory Security tab from the Properties dialog box. Click the Edit button under Secure Communications. In the Secure Communications dialog box, check the Require Secure Channel when accessing this resource box, select Require Subscriber Certificates, and check Enable Subscriber Certificate Mapping. Click the Edit button in the Secure Communications dialog box. Account Mappings dialog box appears. Make sure the Advanced tab is selected (Figure A-15). Click Add to add a new rule. In the General dialog box (Figure A-13), provide a description of the new rule. Determine whether you are going to apply the rule to only specific CAs or all those that you trust.
8 9
It is always recommended to narrow the number of trusted issuers. You can, for example, trust only the root of your Managed PKI hierarchy.
Note
BT38-MPKI6-TRF-V1.1
171
10
Click Next to open the Rules dialog box. (Figure A-10).
Figure A-10 Rules dialog box

11
Click New to edit the rule (Figure A-11). Implement the mapping rules according to your organizations policy. You can use the * (asterisk) wild card character.
Figure A-11 Editing a new rule
172
BT38-MPKI6-TRF-V1.1
12
Click OK. Your new rule appears in the Rules dialog box (Figure A-12).
Figure A-12 A new mapping rule

13
Click Next. Determine the Windows account you should use for mapping (Figure A-13).
Figure A-13 General dialog box
BT38-MPKI6-TRF-V1.1
173
14
Click Finish. The new rule appears in the Account Mappings box (Figure A-14). You can use the Move Up or Move Down buttons to reorder the rules.
Figure A-14 Configured account mapping
Because IIS uses the first matching rule for account mapping, the rules should be ordered from the most specific at the top to the least specific at the bottom.
Note
It is recommended to have your last rule apply to all remaining certificates and refuse access. That way, any certificate that does not match one of your other rules will not be allowed to connect to the server.
One method for doing this is to use the wildcard to match against the Serial Number of the certificate, and then refuse access. Without this last rule, certificate holders with no match would be allowed to connect to your Web server with the default Internet user account (IUSR_[servername].)
174
BT38-MPKI6-TRF-V1.1
15
Determine how you intend to handle revocation of access privileges. Install the VeriSign Managed PKI Certificate Validation Module (CVM) on the Web server if required.
Figure A-15 Account Mappings window, Advanced tab
Figure A-16 Mapping a rule to a Windows account
BT38-MPKI6-TRF-V1.1
175
1
Use VeriSign Managed PKI to issue a subscriber (browser) Digital ID for yourself. Define a new mapping rule that maps your certificate to an account that has access privileges to a resource. Use the Digital ID to access that resource on the Web server. Issue another Digital ID that does not pass the mapping rule. You should not be able to access a restricted resource on the server. Test revocation.
Netscape Examples: Web Server Solutions

This section describes in detail how you can use Netscape technology to implement each access control solution described in this document.
Installing a Server Certificate

Refer to your supplier for instructions on installing server certificates.
Just Trust the Root (Netscape)

The quickest method to implement an access control system using Netscape is to configure the Web server to authenticate users based on the issuer of their certificates. Once authenticated, users can access a restricted resource. No further authorization checking is performed. To deploy this scheme, you must have an Managed PKI private hierarchy (there is no workaround for public hierarchies like as there is for IIS). You should also configure the Web server to check for revoked certificates. Follow these instructions:
1
Enable SSL on the Web server. Install the private CA root in the Web Server. Point your browser to the Managed PKI Control Center, and click the Install CA link in the
176
BT38-MPKI6-TRF-V1.1
Configuration menu. Copy the CA certificate that appears in the page (Figure A-17).
Figure A-17 Install CA page in Managed PKI Control Center

2
In the Netscape Administration Server, select the Keys & Certificates menu under GENERAL ADMINISTRATION and then click the Install Certificate link. Paste the root (CA) certificate in the Message text area. Add the text -----BEGIN CERTIFICATE----- as the first line of the certificate. Add the text -----END CERTIFICATE----- as the last line of the certificate.
BT38-MPKI6-TRF-V1.1
177
Select Trusted Certification Authority (Figure A-18) and click OK. Follow the instructions to install your root.
Figure A-18 Installing a trusted CA in Netscape

4
Configure the list of trusted roots on the Web server. (Click the Manage Certificates link under the Keys & Certificates menu. Make sure to enable the Managed PKI private root and disable all the other roots.) If you leave a public root enabled, a subscriber with a certificate issued by a root other than your private root can access the Web resources.
Select your server instance from the Netscape Administration Server. Require subscriber certificate authentication by choosing the Encryption Preferences link under the Server Preferences menu and setting Require subscriber certificates to yes. Restart the Web server. Install the VeriSign Managed PKI Certificate Validation Module on the Web server. Refer to Manged PKI Certificate Validation and Parsing Guide for instructions.
6 7
Use Managed PKI to issue a subscriber (browser) Digital ID for yourself. Use the Digital ID to access a resource on the Web server. Access Managed PKI to revoke your Digital ID and update the CRL. You should no longer be able to access the Web server. Try to access the Web using a certificate issued by a root other than your own. Access should be denied. It is best to use a certificate issued by a public root you disabled when you configured the list of trusted roots.
Map to User Accounts In LDAP (Netscape)

Designing an access control system using user accounts in an LDAP directory is a three-step process.
1
Configure user and group information. Configure user and group information in the database, either a local database or Netscape Directory Server (LDAP). Because you first install the administration server, you can configure the server to use either a local database or a directory server. You can, however, change this configuration later after the administration server is installed, as described in Configuring an Access Control System With User Accounts in an LDAP Directory (Netscape) on page 183.
Use the Netscape administration server to restrict access to resources. The process of access restriction involves choosing a resource and specifying a list of users and groups with their corresponding access rights to that resource. Designate the authentication method, which can be default, basic, SSL, or other. In the basic authentication method, a user must provide a user name and password to gain access to the resource. The Netscape Web server first confirms the users identity by looking up the username and password in the database (authentication) and then uses the ACL associated with the resource to determine whether it should grant the access (authorization).
With the SSL authentication, the Web server uses the subscriber certificate to search the database for the users entry. If the entry is found, the server can optionally compare the certificate received against the certificate in the directory. The next two sections discuss in more detail how the server searches the database.
Note
BT38-MPKI6-TRF-V1.1
179
If the Web server can successfully map the certificate to a user account, it proceeds to authorize the user by using the mapped account in conjunction with the ACL on the resource.
4
Define exactly how the Web server searches for the user entry in the LDAP database. You should configure the certmap.conf mapping file, and decide whether you need to customize the Certificate Mapping API. The next two sections provide more information on the certmap.conf file and the Certificate Mapping API.
Certmap.conf Configuration File
You can customize the process of mapping a subscriber certificate to a user account by defining how the Netscape Web server searches the LDAP directory for a users entry. You can also specify whether the server should verify that the submitted subscriber certificate matches the users certificate in the directory. The certmap.conf mapping file, which contains the above customization information, determines: The branch in the LDAP tree where the server should begin its search. The certificate attributes that the server should use as search criteria when searching for the entry in the LDAP directory. Whether the server should compare the submitted subscriber certificate with the certificate under the users entry. To customize the mapping process, you must edit the certmap.conf file, which is located under <server_root>/userdb/. For details on configuring this file, refer to Managing Netscape Servers (a manual) or see Certificate-Mapping Programmers Guide. These documents are available from Netscape. This section includes an overview of this file taken from these sources. You can use the following properties in the certmap.conf file:
DNComps. A list of comma-separated attributes used to determine where in the
LDAP directory that the server should start searching for entries that match the certificate subjects information. The server substitutes values for these
180
BT38-MPKI6-TRF-V1.1
attributes from the subscriber certificate to form an LDAP distinguished name (DN). For example, if you set DNComps to use the o and c attributes of the DN, the server starts the search from the o=org, c=country entry in the LDAP directory.
FilterComps. A list of comma-separated attributes used to create a filter by
substituting information from the subject DN of the subscriber certificate. For example, if you set FilterComps to use the e-mail and user ID attributes, the server searches the directory for an entry whose values for e-mail and user ID match the certificate subjects information.
VerifyCert. This flag takes a binary value (on or off) and instructs the server
whether it should compare the subscriber certificate with the certificate found in the LDAP directory.
CmapLdapAttr. If there is a CmapLdapAttr property in the certmap.conf
file, the server searches the entire LDAP directory for an entry whose attribute, named with this property, matches the certificate subjects DN. If the search does not find any matches, the server reverts to using the DNComps and FilterComps mappings.
library. The pathname to a shared library or DLL. This property is used only
if you are customizing the certificate mapping API (explained in Certmap.conf Configuration File for Managed PKI (Netscape) on page 182).
InitFn. The name of an initialization function from a custom library, used only if you are customizing the certificate mapping API Example certmap.conf File
Here is an example certmap.conf file with one default mapping:

certmap default default default:DNComps ou, o, c default:FilterComps e, uid default:VerifyCert on
In the example, the server determines the starting search branch in LDAP by collection values for the organizational unit (ou), organization (o), and country (c) of DNComps from the subscriber certificate subject DN.
BT38-MPKI6-TRF-V1.1
181
The e-mail address and user ID from the subscriber certificate are used to search for a match in the LDAP directory, as identified by FilterComps. Finally, the server is instructed to match the subscriber certificate against the one stored in the directory when it finds a matching entry in LDAP.
Certmap.conf Configuration File for Managed PKI (Netscape)

BT Trust Services recommends that you define only one entry, regardless of whether you are on a public, private, or co-branded Managed PKI hierarchy. Rather than defining a default rule that matches all certification authorities, define a rule that matches only the Managed PKI CA. The values for DNComps and FilterComps depend on how you intend to map certificate subject DNs to entries in LDAP. For example, if you have configured a branch in LDAP whose organization name is the same as the organization field present in subject DNs, a reasonable value for DNComps is o. For FilterComps, you can use e and cn, assuming that you are using e-mail and common name attributes for LDAP entries. The value of verifycert depends on whether you actually store subscriber certificates in the LDAP directory. Set verifycert to on if LDAP stores subscriber certificates. Otherwise, set verifycert to off. The following entry shows one possible set of values for a private Managed PKI hierarchy. (If this is the only rule in certmap.conf, only certificates issued by CN=VSTechSupportPrivate2c, O=VS are considered for possible matches with LDAP entries.)
certmap vrsnCN=VSTechSupportPrivate2c, O=VS vrsn:DNCompso vrsn:FilterCompse, cn vrsn:verifycerton Certificate Mapping API
You can also configure the mapping process programatically through a set of API functions, referred to as the Certificate Mapping API. The main API function calls into three other API functions to find a certificate subjects entry in the directory. It first calls the certificate mapping function, which uses the submitted certificate and the certmap.conf file to generate a base DN and
182
BT38-MPKI6-TRF-V1.1
a search filter. The base DN determines the entry from which the search should begin. For example, if the base DN is <O=ACME, C=US>, a subtler search looks up through all entries in the directory that have <O=ACME, C=US> in their distinguished names. The base DN and search filter is passed to the certificate search function, which actually searches the directory for the certificate subjects entry and returns a list of matching entries. Finally, the main API function calls the certificate verification function to narrow down the list to a single matching entry and verify that the entry has an associated certificate. The three functions described above define the process of finding a certificate subjects entry in the directory. You can write your own versions of the functions, compile them into a shared library or a dynamic linked library (DLL), and modify the certmap.conf file to load your library and use the customized functions instead of the default API functions. To use this API, you need a copy of the Directory SDK, available from the Netscape DevEdge site at http://developer.netscape.com.
Configuring an Access Control System With User Accounts in an LDAP Directory (Netscape)
Follow these instructions to configure an access control system with user accounts in an LDAP directory.
1
When you install your LDAP directory, you must enable the option that allows LDAP to be used with Web servers. If this option is not enabled, Netscape Web servers cannot integrate with LDAP. Determine whether you want to store certificates in LDAP. Managed PKI provides a Directory Integration Toolkit that you can use to populate your LDAP with certificates. The Managed PKI Automated Administration option is required if you want to use this toolkit. Make sure SSL is enabled on the Web server. If you are using an Managed PKI private hierarchy, follow steps 2 through 4 of the previous section to install your private root and to configure the list of trusted roots on the Web server.
3 4
BT38-MPKI6-TRF-V1.1
183
If you are using a public hierarchy, restrict the list of trusted roots to only the VeriSign Class 2 Public Primary CA. Select your server instance from the Netscape Administration Server. Require subscriber certificate authentication by choosing the Encryption Preferences link under the Server Preferences menu and setting Require subscriber certificates to yes. Configure the directory service (Figure A-19). However, skip this step if you configured the service when you installed the Netscape Administration Server.
Figure A-19 Configuring the directory service in Netscape
In the Netscape Administration Server under GENERAL ADMINISTRATION, click Global Settings and select the Configure Directory Service link (Figure A-20). Select Local Database or LDAP Directory Server in the Obtain Directory Service From field. If you choose LDAP Directory Server, you need to provide the host name and port number of the directory server. Refer to the Netscape online help for a description of the fields.
8
Configure account information for users in the LDAP database.

BT38-MPKI6-TRF-V1.1
184
Design and implement your access control policy in the Web server. From the Server Preferences menu, click the Restrict Access link (Figure A-21). Under Pick a resource, select a resource and click the Edit Access Control button (Figure A-21). Figure A-22 shows the user interface to define an ACL. Figure shows what happens when you click anyone under User/Groups. In the User/Group dialog box, provide the group and user information, as entered in LDAP, and choose SSL as the authentication method.
Figure A-20 Configuring the LDAP directory service in Netscape
BT38-MPKI6-TRF-V1.1
185
Figure A-21 Restricting access in Netscape
Figure A-22 Defining an ACL
186
BT38-MPKI6-TRF-V1.1
Figure A-23 User/Group dialog box
For details on defining ACLs, refer to the Netscape online documentation.

10 11 12 13
Configure the certmap.conf file. Customize the Certificate Mapping API, if needed. Restart the Web server. If you are planning to check for revocation information, install the VeriSign Managed PKI Certificate Validation Solution Kit on the Web server. See the Manged PKI Certificate Validation and Parsing Guide for instructions.
Recommended Testing
The following test scenario tests basic functionality of the access control system:
1 2 3 4 5
Use Managed PKI to issue a subscriber (browser) Digital ID for yourself. Set up an account for yourself in LDAP. Configure the certmap.conf file to map your Digital ID to your account. Setup an access control rule. Issue another Digital ID that does not pass the mapping rule. You should not be able to access a restricted resource on the server. Test revocation.
187
BT38-MPKI6-TRF-V1.1
Implementation Guidelines for Managed PKI Web Access Control

This section provides guidelines for implementing an access control solution using Managed PKI. Refer to the corresponding sections in this document for more detailed information.
1 2
Install and configure Managed PKI. Decide whether you want to use the Managed PKI Local Hosting and Automated Administration options. Decide whether you want to use the Managed PKI Personal Trust Agent option. Pick an access control model. Determine what information must appear in each certificate to support your access control model. Run the Policy Wizard to configure the end-user enrollment pages. Determine your revocation checking method(s). Ideally, your access control system should warn users if their certificate is about to expire. Alternatively, if feasible, it should renew their certificates automatically.
4 5
188
BT38-MPKI6-TRF-V1.1
APPENDIX B
Characters Allowed in Digital Certificates

BxidnepA
VeriSign uses industry standards to ensure that Certification Authorities (CAs) and certificates as supplied by BT Trust Services are readable across different platforms and character encoding formats. Character encoding formats specify how computers process the characters for a given language. To meet these standards, VeriSign CA and certificate information can contain only specific characters. Users can enroll for certificates using any of the encoding formats that BT Trust Services supports. For information on supported encoding formats, see Managed PKI Installation and Configuration or Key Management Service Installing Managed PKI with Key Management Service. VeriSign certificates are encoded in the encoding used by the user. The certificate encoding is associated with the certificate. This enables consumers of the certificate to properly interpret and display certificate data. This appendix includes the following topics: Characters Allowed on Administrator Pages on page 190 Characters Allowed on End-user Enrollment Pages on page 191
BT38-MPKI6-TRF-V1.1
189
Characters Allowed on Administrator Pages

When applying for the initial Managed PKI service or for an administrators certificate, you can use any character in the UTF-8 character set, except for the fields shown in the table below.
Table B-1 Fields restricted to non-UTF-8 characters on administrator pages
Field Name Company/Department/ Agency (Organization) Input Type T61 Character Set A through Z, a through z, 0 through 9, spaces, and the following special characters: !"#$&'()+,-./:;<>@_ 0x0D and all upper 128 characters (This includes most European alphabets). The following characters are not permitted: %*=?[]\^`{}|~ Division/Organization/ Project (Organization Unit) T61 Note: Only ASCII characters are allowed. A through Z, a through z, 0 through 9, spaces, and the following special characters: !"#$&'()+,-./:;<>@_ 0x0D and all upper 128 characters (This includes most European alphabets). The following characters are not permitted: %*=?[]\^`{}|~ All fields requesting country All fields requesting telephone numbers All fields requesting e-mail addresses TEXT PHONE EMAIL Note: Only ASCII characters are allowed. 0 through 9, spaces, and the following special characters: ( ) Note: Only ASCII characters are allowed. A through Z, a through z, 0 through 9, and the following special characters: ! ( ) + ./:@_
190
BT38-MPKI6-TRF-V1.1
Appendix B Characters Allowed in Digital Certificates
Characters Allowed on End-user Enrollment Pages

If you selected UTF-8 encoding in the Policy Wizard, your end users can enter UTF-8 characters in all enrollment fields, except for the fields shown in the table below.
Table B-2 Fields restricted to non-UTF-8 characters on end-user enrollment pages
Field Name All fields requesting country All fields requesting telephone numbers All fields requesting e-mail addresses Input Type TEXT PHONE EMAIL Character Set Note: Only ASCII characters are allowed. 0 through 9, spaces, and the following special characters: ( ) Note: Only ASCII characters are allowed. A through Z, a through z, 0 through 9, and the following special characters: ! ( ) + ./:@_ TEXT Note: Only ASCII characters are allowed.
Passocode (if you implement passcodes)
A through Z, a through z, 0 through 9, spaces, and the following special characters: ' ( ) + , - . / :
BT38-MPKI6-TRF-V1.1
191
192
BT38-MPKI6-TRF-V1.1
APPENDIX C
Understanding How BT Trust Services Generates Certificates

CxidnepA
This appendix gives an overview of the information path from initiation of a request on the client browser, through the processing center, and back to the originating browser. The progression is essentially the same for Local Hosting and BT Trust Services-hosted situations. A typical process flow is shown in Figure C-24.
Figure C-24 Request process path
The following example describes the steps involved when a subscriber searches for an associates certificate.
1
A subscriber wants to send encrypted e-mail to an associate, which requires the associates certificate. To locate and download the certificate, the subscriber
BT38-MPKI6-TRF-V1.1
193
uses a browser to access the Digital ID Center index page, shown in Figure C-25.
Figure C-25 Digital ID Center index page

2
The subscriber clicks the Search link to open the Search for Digital IDs page (Figure C-26).
194
BT38-MPKI6-TRF-V1.1
Appendix C Understanding How BT Trust Services Generates Certificates
In the Search for Digital IDs page (Figure C-26), the subscriber enters the associates e-mail address and selects all certificates. Then, the subscriber clicks the Search button to submit the form.
Figure C-26 Search for Digital IDs page

4
Through the HTTP POST operation, the form is submitted to a CGI program, hosted at BT Trust Services. Using a form definition file (FDF) associated with the Find Certificate page, the CGI program extracts the specified values from the form (in this example, jane@acme.com and all certificates). The CGI program then passes these values to the VeriSign software that processes the request. The VeriSign software locates all certificates for jane@acme.com and passes the response value (the list of certificate information for jane@acme.com) back to the CGI program. Then, the CGI program passes this value to another CGI program (haydn) which is hosted on your Web server. Using FDFs, haydn
BT38-MPKI6-TRF-V1.1
195
converts the values to named variables and displays the Search Results VHTML (Variable HTML) page to the subscriber (see Figure C-27).
Figure C-27 Certificate search results page
196
BT38-MPKI6-TRF-V1.1
APPENDIX D
Using Netscapes Directory Server with Managed PKI LDIF Files

DxidnepA
This appendix includes the following sections: Using Managed PKI LDIF Files with Netscape iPlanet 4.x on page 197. Importing Managed PKI LDIF Files into iPlanet Directory Server v5.0 on page 204.
Using Managed PKI LDIF Files with Netscape iPlanet 4.x

Disclaimer: The information contained in this appendix is distilled from VeriSign's experience with the Netscape Directory Server, and Netscape/Microsoft client products. It is intended to get you started quickly, but may not be completely suited for your environment. For complete information, refer to the appropriate Netscape and Microsoft documentation.
CAUTION
Follow the these steps to set up and configure the directory (iPlanet Directory Server 4.x). These instructions assumes that you are building a directory server from scratch. You can omit the initialization steps if you already have a directory server up and running.
Installation and Initialization

Run ns-setup and follow the directions given you. See your documentation and online help for more information.
BT38-MPKI6-TRF-V1.1
197
Configuration
Configure Server Configure your server according to recommendations from the Netscape LDAP Server documentation. Your configuration should include all database tuning parameters (allidthreshold, dbcache, cache) as well as server configuration (port number, user, admin account and password, modification tracking on/off and so on). Define Schema You must define a schema for your directory that is compatible with Managed PKI. Managed PKI defines a new attribute type, and two new objects for storage in the directory: branch and subscriber (or entry). These objects are named using the attribute objectclass. Following is an example of the Managed PKI attribute and object definition.
Managed PKI Attribute Definition
Cut and paste this text into a file called slapd.vs.at.conf:

attribute unstructuredAddress cis
Managed PKI Object Definition:
Cut and paste this text into a file called slapd.vs.oc.conf:

objectclass entry requires objectClass allows userSMimeCertificate;binary, sn, st, "brought by", unstructuredAddress, street, serialnumber, userCertificate;binary, userCertificate, cn, c, mail, labeleduri, o, ou, l
Appendix D Using Netscapes Directory Server with Managed PKI LDIF Files
objectclass branch requires objectClass allows userSMimeCertificate;binary, sn, st, "brought by", unstructuredAddress, street, serialnumber, userCertificate;binary, userCertificate, cn, c, mail, labeleduri, o, ou, l objectclass subscriber requires objectClass allows userSMimeCertificate;binary, sn, st, "brought by", unstructuredAddress, street, serialnumber, userCertificate;binary, userCertificate, cn, c, mail, labeleduri, o, ou, l
BT38-MPKI6-TRF-V1.1
199
Adding Object Definitions To add the objectclass definitions to your server, modify your slapd.conf file (located in the config subdirectory of your server instance). Your slapd.conf file begins with commented lines that start with hash marks (#), followed by lines that include other files. You should add new lines to include the attribute and object definition file. The first few lines of your slapd.conf should now resemble the following:
# Used by Netscape Directory Server include /usr/netscape/server4/slapd-myServer/config/slapd.at.conf include /usr/netscape/server4/slapd-myServer/config/slapd.vs.at.conf include /usr/netscape/server4/slapd-myServer/config/slapd.oc.conf include /usr/netscape/server4/slapd-myServer/config/slapd.vs.oc.conf access log /usr/netscape/server4/slapd-myServer/logs/access
The ordering of the include files is critical. You must include slapd.at.conf before slapd.vs.at.conf. You must include slapd.vs.at.conf and slapd.oc.conf before slapd.vs.oc.conf.
Note
Choosing a Base DN You will have to choose a baseDN. Your baseDN is comprised of the maximum amount of static naming information you want to store in your directory. Typically, this will be your Company and Department name, which is the top few levels of your Subscriber Certificate's Subject Names. This portion of the name is static across all Certificates that you publish to your directory. For example, a good choice might be a baseDN of o=MyCompanyName,ou=MyDepartmentName Once you have selected your baseDN, you should modify your slapd.conf file to reflect this. You will also have to choose an administrative account name and password and create access control information (who is allowed to search the directory, who is allowed to add/delete information from the directory, etc.). See your directory server documentation and online help for more information. If you are using an existing directory, create a new suffix for the top-level entry in your LDIF file (if it does not yet exist).
200
BT38-MPKI6-TRF-V1.1
Create Directory
Once you have installed and configured your directory server, you are ready to create your initial directory. This can be done through the Netscape administrative server UI or through the ldif2db command. See your server documentation and online help for more information on creating your directory. Once you have created your directory, verify that it contain access control information and an entry for your baseDN. Adding data to the directory You can add data to your directory using Netscape's ldapmodify command and the LDIF file that you downloaded from Managed PKI. To add data, issue the following command with the appropriate LDIF file name, administrator user name, and password:
ldapmodify -a -h <LDAP host> -p 389 -D "cn=Directory Manager" -w "password" -c -v -f <LDIF file>
The -c flag (required) indicates that the utility should continue to process even if it encounters a duplicate entry. Remove data from the directory Your can remove data from your directory using Netscape's ldapdelete command and the remove LDIF file you downloaded from Managed PKI. To remove data, issue the following command with the appropriate LDIF file name, administrator user name, and password:
ldapdelete -h <LDAP host> -p 389 -D "cn=Directory Manager" -w "password" -f <LDIF file to remove>
Using your directory

Using your directory requires that you configure your client application. Refer to your client documentation for more information. The following are condensed information for using your directory with Netscape and Microsoft clients. Configuring the Netscape Communicator Directory Interface
1 2 3
Start Communicator. In the Edit menu, select Preferences. Expand Mail & Groups.
BT38-MPKI6-TRF-V1.1
201
4 5 6 7 8
Select Directory. Select New. Enter a friendly name in the Description field. Enter the name of your directory machine in the LDAP Server field. Click OK.
Configuring the Windows Address Book Directory Interface

1 2 3 4 5 6
In the task bar, click Start. Select Find from the program list. Select People from the Find list. In the Look In box, select Directory Services. Click Add. In the Internet Directory (LDAP) server field, enter the name of your directory host. Click Next. Click Next again. Enter a friendly name in the Internet Directory Service Name field. Click Finish. Select the friendly name from Step 9 in the Internet Accounts window. Select Properties. Click the Advanced tab. Select the Use Simple Search Filter option. Click OK.
7 8 9 10 11 12 13 14 15
Using Netscape Communicator to send secure e-mail

1 2
Select Compose New Message (CTRL-M). Select an addressee.
202
BT38-MPKI6-TRF-V1.1
3 4 5 6 7 8 9 10 11
Enter a subject and a body for the message. Click the Security button. If the upper right pane indicates that you may encrypt the e-mail, skip to Step 8. Click the Get Certificates button. Select the friendly name that you created in Step 9 on page 202. Click OK to close the Netscape Security Advisor. Click the Select Message Options tab. Click Encrypt. Click Send.
Using Outlook Express to send secure e-mail

1 2 3 4 5
Select Compose Message (CTRL-N). Select an addressee. Enter subject and body for the message. Click the Encrypt Message button on the task bar. Click Send. If you did not successfully send encrypted mail, continue with Step 6. In the Tools menu, select Address Book. Click the Find button in the toolbar. Select the friendly name that you created in Step 9 on page 202. Enter the name or e-mail address of the addressee. Click Find. A result list should appear. If the list is empty, then your addressee was not found in the directory. Double-click the entry that you wish to view. Confirm this is the entry you want (confirm e-mail address). Click Add to address book. Click OK.
6 7 8 9 10
11
12 13
BT38-MPKI6-TRF-V1.1
203
14
Click Send.
Importing Managed PKI LDIF Files into iPlanet Directory Server v5.0
For iPlanet Directory Server 5.0, follow these steps to import Managed PKI LDIF files:
Step 1
Create the required Managed PKI schema extension in the LDAP server
VeriSign Managed PKI LDIF uses the following new attributes (See slapd.vs.at.conf and slapd.vs.oc.conf): unstructuredAddress and new objectclasses: branch subscriber You can perform this task from either the command line or Console. The following instructions describe the Console method. To create the new attribute unstructuredAddress:
1 2 3
Login as admin and switch to user cn=Directory Manager. Select the Configuration tab of the target LDAP server. In the left navigation tree, select the Schema folder and select the Attributes tab. Click Create. The Create Attribute dialog box appears. Enter unstructuredAddress in the Attribute Name text box. Optional: Enter an object identifier for the attribute in the OID text box. Select a syntax that describes the data to be held by the attribute from the Syntax menu. Select Directory String in this example. If you want the attribute to be multi-valued, select the Multi-Valued checkbox. Do not select any other items for this attribute.
4 5 6 7
204
BT38-MPKI6-TRF-V1.1
Click OK.
To create the new objectclass branch:

1
On the Configuration tab, in the left navigation tree, select the Schema folder and then select the Object Classes tab in the right pane. Click Create. The Create Object Class dialog box appears. Enter branch for the attribute in the Object Class Name text box. Optional: Enter an object identifier for the object class in the Attribute OID text box. Select a parent object for the object class from the Parent menu. Select Top for this example. To add an attribute that may be present in entries that use the new object class, highlight the attribute in the Available Attributes list and then click the Add button to the left of the Allowed Attributes box. Repeat this step for each of the allowed attributes listed for this objectclass in the slapd.vs.oc.conf file. When you are satisfied with your object class definition, click OK.
2 3 4
Step 2
Create a new suffix

You can perform this task from either the command line or Console. The following instructions describe the Console method.
1 2
On the Directory Server Console, select the Configuration tab. Right-click Data in the left navigation pane and select New Root Suffix. The Create new root suffix dialog box appears. Enter a unique suffix in the New Suffix field. Enter c=US. Select the Create associated database automatically checkbox if a database should be created at the same time as the new root suffix. Deselect the checkbox to create a database for the new root suffix later. You may want to do this to be able to specify a directory in which the database will be created. The new root suffix is disabled until you create a database.
3 4
If you selected the Create associated database automatically checkbox in page 205, enter a unique name for the new database in the Database name field.
205
BT38-MPKI6-TRF-V1.1
Click OK to create the new root suffix. The suffix appears automatically under the Data branch in the left navigation pane.
Step 3
Import the File Into the Database

You can perform this task from either the command line or Console. The following instructions describe the Console method. To import data from the Directory Server Console:
1
On the Directory Server Console, select the Tasks tab. Scroll to the bottom of the screen and select Import Database. You can also import by going to the Configuration tab and selecting Import from the Console menu. The Import Database dialog box appears.
In the LDIF File field, enter the full path to the LDIF file to import. Alternatively, click Browse to select the file. If you are running the console on a computer remote to the directory, the field name appears as LDIF file (on the computer running the console). This reminds you that when you browse, you are not browsing your current directory. Instead, you are browsing the file system of the machine running the console.
In the Options box, select one or more of the following options: Add Only. The LDIF file may contain modify and delete instructions in addition to the default add instructions. If you want the server to ignore operations other than add, select the Add Only check box. Continue on Error. Select the Continue on error checkbox if you want the server to continue with the import even if errors occur. For example, you might use this option if you are importing an LDIF file that contains some entries that already exist in the database in addition to new ones. The server notes existing entries in the rejects file while adding all new entries.
206
BT38-MPKI6-TRF-V1.1
In the File for Rejects field, enter the full path to the file in which you want the server to record all entries it cannot import. Alternatively, click Browse to select the file. For example, the server cannot import an entry that already exists in the database or an entry that has no parent object. The console writes the error message sent by the server to the rejects file. If you leave this field blank, the server will not record rejected entries.
Click OK. The server performs the import and also creates indexes.
BT38-MPKI6-TRF-V1.1
207
208
BT38-MPKI6-TRF-V1.1
APPENDIX E
Adding Fields to the Subscriber Enrollment Pages

ExidnepA
This appendix describes the process for adding input fields to the subscriber enrollment page. You can add fields to these pages only if you are locally hosting the Digital ID Center pages.
Modifying the Subscriber Enrollment Pages

To add a field to the enrollment page, you must modify three files; the HTML enrollment form, the corresponding FDF file, and the enroll_wait.htm file.
Modifying the HTML Pages

Modify the appropriate enrollment HTML pages by adding an <INPUT> tag for the new field. Table E-3 lists the subscriber enrollment pages.
Table E-3 Subscriber enrollment pages to modify
HTML page userEnrollCSRMain.htm userEnrollCSRVPN.htm userEnrollDualNS.htm userEnrollDualMS.htm userEnrollEnc.htm userEnrollEncMS.htm Description Main CSR enrollment page CSR for VPN enrollment page Netscape enrollment page for dual key Internet Explorer enrollment page for dual key Netscape enrollment page for single (encryption) key Internet Explorer enrollment page for single (encryption) key
BT38-MPKI6-TRF-V1.1
209
Table E-3 Subscriber enrollment pages to modify

HTML page userEnrollEncNotes.htm userEnrollEncNS.htm userEnrollMS.htm userEnrollNotes.htm userEnrollNS.htm Description Lotus Notes enrollment page for single (encryption) key Netscape enrollment page for single (encryption) key redirected from userEnrollEncNotes.htm Main Internet Explorer enrollment page (non-KMS) Main Lotus Notes enrollment page (non-KMS) Main Netscape Navigator enrollment page (non-KMS)
The following is an example of the <INPUT> tag for a new field called userid:
<INPUT NAME=userid TYPE=text VALUE="" SIZE=20 MAXLENGTH=30>
Modifying FDF Files

Modify the appropriate FDF file by adding a line defining the new field. Table E-4 identifies which FDF file to modify, based on the subscriber enrollment HTML page you modified.
Table E-4 FDF files to modify
HTML Page Modified userEnrollCSRMain.htm FDF File to Modify userEnrollCSRMain.fdf userEnrollCSRMain.fdf.testdrive userEnrollCSRVPN.htm userEnrollCSRVPN.fdf userEnrollCSRVPN.fdf.testdrive userEnrollDualMS.htm userEnrollDualNS.htm userEnrollEncMS.htm userEnrollEncNotes.htm userEnrollEncNS.htm userEnrollMS.htm userEnrollDualMS.fdf userEnrollDualNS.fdf userEnrollEncMS.fdf userEnrollEncNotes.fdf userEnrollEncNS.fdf userEnrollMS.fdf
210
BT38-MPKI6-TRF-V1.1
Appendix E Adding Fields to the Subscriber Enrollment Pages
Table E-4 FDF files to modify

HTML Page Modified userEnrollNotes.htm userEnrollNS.htm FDF File to Modify userEnrollNotes.fdf userEnrollNS.fdf
The following is an example of the line defining a new field called userid.
userid TEXT MANDATORY NONE NONE
Modifying enroll_wait.htm
Modify the enroll_wait.htm file by adding an INPUT TYPE tag for the new field. The following is an example of the INPUT TYPE tag for a new field called userid.
<INPUT TYPE=hidden NAME=userid TYPE=hidden VALUE="$$common_name$$">
Predefined Fields
Any field you add that is not predefined by VeriSign will not be returned by BT Trust Services as part of the certificate. Values entered by your subscribers in these fields are not available to AA for entry into your registration data source. However, VeriSign has predefined several customizable fields that do get returned with the certificate. Use these fields to add customized subscriber data to your registration data source. password. This field provides the subscribers password to AA, but unlike the other predefined fields, does not pass the value to BT Trust Services. Go Secure for Lotus Notes uses this field by default. common_name. This field allows the subscriber to enter his or her full name in one field rather than entering the first and last name in separate fields. This field gets passed to BT Trust Services and then back to AA for registration. You might use this field if you are pre-populating the enrollment page from a database or directory, and the subscribers name is stored as a full name. When using this predefined field, you must also remove the FirstName and LastName fields from the enrollment pages, FDF files, and enroll_wait.htm file.
BT38-MPKI6-TRF-V1.1
211
user_data. VeriSign has predefined five fields for subscriber data that can be added to the registration data source but do not need to be in the certificate: user_data_1 through user_data_5. These fields are passed to BT Trust Services and then back to the customer for registration. The user_data fields are already defined in the FDF files and in enroll_wait.htm, so you need only to add an <INPUT> tag to the enrollment pages to use them.
212
BT38-MPKI6-TRF-V1.1
APPENDIX F
Removing Fields from the Certificate Enrollment Form

F xidnepA
This appendix describes how to remove a field from the standard Digital ID enrollment form. You can remove fields from these pages only if you are locally hosting the Digital ID Center pages. For example: If you are retrieving users Common Names from a directory or database, you may want to remove the First Name and Last Name input fields from the enrollment form. If you are not manually approving certificates, you may want to remove the Comments field. If your organization requires users to contact an administrator to revoke their certificate, you can remove the Challenge Phrase field from the enrollment page.
Overview
Removing a field from the enrollment pages is a relatively simple process, but it requires manual modification of the policy file, so it must be done with care. The policy file is created in the Control Center and lists the options for your account. Whenever you need to make a change to your account, you run the Policy Wizard from the Control Center and download a new policy file. Making manual changes to the file is discouraged, but sometimes useful, as in the case of removing a field from enrollment. Any manual edits that you make to the policy file will be lost each time you download a new policy file from the Control Center. Be sure to keep track of the
changes that you make so you can re-apply them if you ever have to download a new copy of the policy file.
Removing a Field
To remove a field from the enrollment pages, you must edit its section or sub-container under the Enrollment section of the policy file. Each enrollment field has a sub-container with variables that tell the customization engine how to customize that field in the enrollment pages. To remove a field, you must edit that fields policyValue entry. For example, to remove the Comments field from the enrollment page, open the policy file in a text editor and change the Comments field policyValue from exists to absent:
. . Comments { # 0 sub containers policyValue:exists bRequired:OPTIONAL
to:
. . Comments { # 0 sub containers policyValue:absent bRequired:OPTIONAL
Once you have made the necessary changes, re-customize the pages by rerunning the install script (as described in Using Customizer Commands on page 8). If you are re-customizing pages you have already installed, be sure to use current install directory as both the source and destination arguments when you run the script:
install-[OS] D:\VeriSign\OnSite\webroot D:\VeriSign\OnSite\ webroot D:\ACMEBank.policy
By changing the policyValue to absent and re-customizing the pages, you allow the customization engine to modify all the appropriate HTML and FDF files to safely remove the Comments field from all the pages. If you ever decide to add the field back, then change the policyValue back to exists and rerun the install script.
214
BT38-MPKI6-TRF-V1.1
Index
Index
A
AA see Automated Administration AA server 29 components 28 aakeygen 42 access denying 155, 156 mapping by user account 154, 164, 169, 179 access control architecture 153 certificate-based 149 native IIS 151 native Netscape 151 using with Managed PKI 188 access control list 151, 154, 155, 165, 179, 185 ACL see access control list Active Directory 100 Active Directory Connect 100 Active Server Pages 165 AIX sitekit directory 13 APIs Automated Administration 50 Signing 56 verification and registration 52 ASP see Active Server Pages augmentation data 93 authentication 150 using an LDAP directory 29 using an ODBC database 29
authorization 150 Automated Administration 27 certificate renewal 36 detailed flow control 48 flow of control 48 linking to data source 87 operational overview 32, 83 signing utilities 41 using the APIs 50 Automated Administration APIs data structures 50 ProcessEntries 53 VSAA_NAME 52 VSAA_STATUS 52 Automated Administration server 29 automatic renewal for Microsoft Internet Explorer users 37 for Netscape Navigator users 37
B
base64 format 62 browser emulation 129 BT Trust Services Issuing Center 32
C
C field 170 certificate fields 170 revoking 154 Certificate Parsing Module 38 certificate proof of possession. 37 certificate renewal automatic 36 client authentication 39 re-authentication 39
BT38-MPKI6-TRF-V1.1
215
Managed PKI Technical Reference certificate revocation list 18, 105, 152 certificate signing request 32, 47 Certificate Validation Module 105, 168, 175 certificate-based access control 149 certificates publishing 130 publishing to Active Directory 100 revoking 18 certmap.conf file 180 CGI program 29, 32, 49 challenge phrase hidden 38 Chrysalis-ITS Luna 30 CmapLdapAttr property 181 CN field see Common Name field commercial HTML editor 11 Common Name field 170 configuration additional Automated Administration 67 changing Managed PKI 11 Control Center 7, 17, 19, 52 Country field 170 CPM see Certificate Parsing Module 38 CRL see certificate revocation list cryptographic protocol 150, 159, 162, 176, 179, 183, 185 CSR see certificate signing request customizer command 8 CVM see Certificate Validation Module 105 see Certificate Validation Module
Digital ID Center pages 6 customizing 11 index page 194 directory entry 97 schema 99 technology overview 95 Directory Access Protocol 98 Directory Information Tree 98 Distinguished Name 98 DN see Distinguished Name DNComps property 180 domain controllers 100
E
end entity certification 133 token 131 enrollment pages 6 entry variables 112 error message text modifying 125 expiration period passcode 23
F
FDF see form definition file fields, certificate 170 FilterComps property 181 firewall 49 form definition file 110, 111, 114, 126, 195
G
Given Name field 171 GN field 171
D
DAP see Directory Access Protocol data source linking to Automated Administration 87 216
H
hardware signing 30, 41, 42 utility 42 BT38-MPKI6-TRF-V1.1
Index haydn 195 haydn.edf file 126 haydn.exe 125 hierarchy private 106 public 106 HP-UX sitekit directory 13 HTML, variable 109
L
L field see Locality field LDAP 155, 179 defined 99 see lightweight directory access protocol library property 181 Lightweight Directory Access Protocol 99 lightweight directory access protocol 151 Local Hosting server 29 flow of control 48 Locality field 170 Luna token 30
I
I field 171 IIS native access control 151 InitFn property 181 Initials field 171 install command see customizer command installing trusted roots 157 ISO Standard Directory Architecture 97
M
Managed PKI Key Management Service 29 modifying configuration 11 private hierarchy 106 public hierarchy 106 modifying error messages 125
J
jurisdiction 107 Just Trust the Root 153 for IIS 162 for Netscape 176
N
name/value pairs 52, 54, 64 browser emulation specification 73, 129 Digital ID enrollment 81 Registration Authority certificate enrollment 79 Netscape Web server solutions 176 Netscape native access control 151
K
Key Management Service 29 security advantages 38 Key Management Services 131 Key Managment Service signing utilities 41 keywords reserved for parameters 122 KMS see Key Management Service
O
ODBC data source configuring 85 operational period 25, 35 Organizational Unit field 170 OU see Organizational Unit field
BT38-MPKI6-TRF-V1.1
217
P
passcode cancelling 21 expiration period 23 used 18 passcode authentication in the Policy Wizard 15 passwords used with certificates 154 PCT see Private Communication Technology pestub 29, 38, 49, 50 pilot system 106 PKCS#12 format 44 PKCS#7 format 43 Policy file 8 Policy Wizard 8, 12, 52 POST target 112 Private Communication Technology 159 private hierarchy 106 ProcessEntries function 52, 53 applicant enrollment authentication 54 certificate pick up 54 certificate registration 55 certificate renewal 55 certificate revocation 55 decrypt operation 56 error notification 56 production system 106 public hierarchy 106
Register function 38 Registration Authority certificate 30 registration data source 30 Registration server 28 renewing certificates 39 replication protocols 97 requiring subscriber certificates 159 reserved name keywords 122 revoking certificates 154
S
S field see State/Province field schema directory 99 Secure Sockets Layer 150, 159, 162, 176, 179, 183, 185 server certificate 158, 176 shared library custom 71 Signing API 56 signing device 30 signing utilities understanding 41 softbounce.exe 112 software signing 41 swimport 43 swkeygen 41 software signing option 30 Solaris see Sun Solaris Sophia modifying error message text with 125 Sophialite 29, 32, 37, 49 SSL 150 see Secure Sockets Layer State/Province field 170 status variables 112 subfields, certificate 170 subject distinguished name 38 RA_dn 41 BT38-MPKI6-TRF-V1.1
R
RA certificate 30 re-authentication renewal 39 re-configuring Managed PKI 11 regInfo IPSec certificates 7779 personal client certificates 7376 value tag definitions 81
218
Index subscriber certificates requiring 159 subscribers adding 19 certificate renewal 36, 39 Sun Solaris 27, 91 sitekit directory 13 swimport utility 43 swkeygen 41 variables entry 112 status 112 verification and registration API 52 verification data source 29, 32 flat-file version 91 VerifyCert property 181 VHTML 51, 109, 196 VSAA_CleanupSigner function 61, 63 VSAA_DecodeCert function 66 VSAA_DecodeCertRep function 56, 63, 65 additional name/value pairs 64 VSAA_EncodeGetCert function 54, 59 VSAA_EncodeGetCRL function 60 VSAA_EncodePKCSReq function 54, 55, 58 VSAA_EncodeRevReq function 55 VSAA_ExchangeMsg function 65, 66 VSAA_ExtractCert function 66 VSAA_FreeName function 63, 64, 65 VSAA_InitSigner function 58 VSAA_NAME 55, 56 VSAA_SetDebugLog function 65, 66 VSAA_STATUS 52, 54 VSAA_SUCCESS 52, 56 vsaasrv 29, 38, 49 vskmsrv 29
T
T field see Title field testing (IIS) 163, 169, 176 testing (Netscape) 178, 187 Title field 171 transient inconsistencies 96 trusted roots installing 157
U
unpopulated list 112 upgrading Managed PKI 11 user account mapping access by 154, 164, 169, 179
V
validity period 25, 35 validuser.txt 91 Variable HTML 109 variable naming, VHTML 128
W
Windows 2000 100, 197
X
X.509 format 43, 44, 66
BT38-MPKI6-TRF-V1.1
219
220
BT38-MPKI6-TRF-V1.1

MPKI6 TechRef

Enviado por

Dados do documento

Descrição original:

Título original

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

MPKI6 TechRef

Enviado por

Direitos autorais:

Formatos disponíveis

Managed PKI

Customer Support: +44(0) 870 608 7878 support@trustwise.com BT38-MPKI6-TRF-V1.1

Managed PKI Technical Reference

Chapter 2 Understanding Local Hosting . . . . . . . . . . . . . . . . . . . . . . 5

Chapter 3 Understanding Passcode Authentication . . . . . . . . . 15

Chapter 4 Understanding the Automated Administration Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Chapter 5 Understanding Subscriber Certificate Renewal . . . 35

Managed PKI Technical Reference

Using Client Authentication Renewal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Addressing Implementation Considerations . . . . . . . . . . . . . . . . . . . . . . 39

Chapter 6 Understanding Signing Utilities . . . . . . . . . . . . . . . . . . . 41

Chapter 7 Working with Automated Administration APIs . . . . 47

Chapter 10 Using a Flat File for Verification Data . . . . . . . . . . . . 91

Chapter 11 Understanding Directory Technology (Overview) 95

Chapter 12 Implementing Native Character Encodings with AA or KMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Chapter 13 Downloading Certificate Revocation Lists . . . . . . 105

Chapter 14 Working With Sophialite . . . . . . . . . . . . . . . . . . . . . . . . 109

Modifying End-User Error Message Text . . . . . . . . . . . . . . . . . . . . . . . . . 125

Managed PKI Technical Reference

Chapter 15 Understanding the Browser Emulation Specification

Appendix A About Certificate-Based Access Control . . . . . . . 149

156 157 162 163 176 176 176 179 182

Implementation Guidelines for Managed PKI Web Access Control . . . . . 188

Appendix B Characters Allowed in Digital Certificates . . . . . . 189

Appendix E Adding Fields to the Subscriber Enrollment Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

Predefined Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

Managed PKI Technical Reference

Appendix F Removing Fields from the Certificate Enrollment Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

About This Manual

Managed PKI Technical Reference

Managed PKI Technical Reference

Understanding Local Hosting

Managed PKI Technical Reference

Introduction to Local Hosting

Figure 2-1 Typical Local Hosting network configuration

Using the Digital ID Center Pages

Chapter 2 Understanding Local Hosting

Figure 2-2 Completion page before customization

Managed PKI Technical Reference

Figure 2-3 Completion page after customization

Using Customizer Commands

Chapter 2 Understanding Local Hosting

install-<nt|sun|hpux|aix> installs or modifies Local Hosting pages. This

Managed PKI Technical Reference

Modifying Digital ID Center Pages

Chapter 2 Understanding Local Hosting

Making Subsequent Modifications to Your Digital ID Center Pages

Managed PKI Technical Reference

Chapter 2 Understanding Local Hosting

Example for Windows 2000:

Example for Sun Solaris:

Example for HP-UX:

Example for AIX:

Managed PKI Technical Reference

Understanding Passcode Authentication

About Passcode Authentication

Managed PKI Technical Reference

Figure 3-4 Overview of Passcode Authentication process

Chapter 3 Understanding Passcode Authentication

Applicant: Request a certificate.

BT Trust Services: Verify the enrollment data

Managed PKI Technical Reference

BT Trust Services: Approve the request