Netscape NETSCAPE MANAGEMENT SYSTEM 6.01 -... User manual

Customization Guide
Netscape Certificate Management System
Version6.01
May 2002

Netscape Communications Corporation ("Netscape") and its licensors retain all ownership rights to the software programs offered by
Netscape (referred to herein as "Software") and related documentation. Use of the Software and related documentation is governed by the
license agreement for the Software and applicable copyright law.
Your right to copy this documentation is limited by copyright law. Making unauthorized copies, adaptations or compilation works is
prohibited and constitutes a punishable violation of the law. Netscape may revise this documentation from time to time without notice.
THIS DOCUMENTATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IN NO EVENT SHALL NETSCAPE BE LIABLE
FOR INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY KIND ARISING FROM ANY ERROR IN THIS
DOCUMENTATION, INCLUDING WITHOUT LIMITATION ANY LOSS OR INTERRUPTION OF BUSINESS, PROFITS, USE, OR DATA.
The Software and documentation are copyright © 2001 Sun Microsystems, Inc. Portions copyright 1999, 2002 Netscape Communications
Corporation. All rights reserved.
Netscape and the Netscape N logo are registered trademarks of Netscape Communications Corporation in the United States and other
countries. Other Netscape logos, product names, and service names are also trademarks of Netscape Communications Corporation, which
may be registered in some countries. Other product and brand names are the exclusive property of their respective owners.
The downloading, exporting, or reexporting of Netscape software or any underlying information or technology must be in full compliance
with all United States and other applicable laws and regulations. Any provision of Netscape software or documentation to the U.S.
government is with restricted rights as described in the license agreement for that Software.

3
Contents
AboutThisGuide.............................................................. 11
What’sinThisGuide....................................................................11
WhatYouShouldAlreadyKnow .........................................................11
ConventionsUsedinThisGuide .........................................................12
WheretoGoforRelatedInformation......................................................14
Chapter 1 BeforeYouBegin ................................................... 17
WhatYouNeedtoKnowtoChangeForms ................................................17
HTTP,QueryURLs,andHTMLForms .................................................18
JavaScript...........................................................................18
HowtheFormsWork ...................................................................18
RequestsSenttotheCMSserver .......................................................19
ResponsesandOutputTemplates ......................................................19
ErrorsandtheErrorTemplate .........................................................21
JavaScriptUsedByAllInterfaces .........................................................22
HowtoRegisterServlets ................................................................26
Part 1 CustomizingEnd-EntityServicesInterface................................ 27
Chapter 2 IntroductiontoEnd-EntityServicesInterface ............................ 29
End-EntityServicesInterface.............................................................29
HowClientTypeDeterminestheEnd-EntityInterface ....................................31
CertificateRequestFormatsSpecifictoEndEntities ......................................32
AccessingtheEnd-EntityServicesInterface ................................................33
End-EntityFormsandTemplates .........................................................33

4 Netscape Certificate Management System Customization Guide • May 2002
LocatingEnd-EntityFormsandTemplates.............................................. 34
FormsforCertificateEnrollment....................................................... 34
FormsforCertificateRenewal ......................................................... 35
FormsforCertificateRevocation....................................................... 36
FormsforCertificateRetrieval......................................................... 36
FormsforKeyRecovery .............................................................. 37
OtherForms ........................................................................ 37
OutputTemplatesforEnd-EntityInterfaces............................................. 38
Chapter 3 End-EntityInterfaceReference........................................ 41
OverviewofEnd-EntityInterfaces........................................................ 42
ApproveRevocationInterface ........................................................... 43
Description ......................................................................... 43
DefaultForms....................................................................... 43
RequestParameters.................................................................. 43
Response ........................................................................... 45
CertificateEnrollmentProtocolInterface .................................................. 47
Description ......................................................................... 47
DefaultForms....................................................................... 47
RequestParameters.................................................................. 47
ChallengeRevocationInterface .......................................................... 48
Description ......................................................................... 48
DefaultForms....................................................................... 48
RequestParameters.................................................................. 48
Response ........................................................................... 50
DisplayCertificateBySerialNumberInterface ............................................. 50
Description ......................................................................... 50
DefaultForms....................................................................... 50
RequestParameters.................................................................. 50
Response ........................................................................... 51
DisplayCertificateFromRequestInterface ................................................ 52
Description ......................................................................... 52
DefaultForms....................................................................... 52
RequestParameters.................................................................. 53
Response ........................................................................... 53
EnrollmentInterface.................................................................... 55
Description ......................................................................... 55
DefaultForms....................................................................... 56
RequestParameters.................................................................. 57
Response ........................................................................... 61
GetCAChainInterface ................................................................. 65
Description ......................................................................... 65
DefaultForms....................................................................... 66

5
RequestParameters ..................................................................66
Response ...........................................................................67
GetCertificateBySerialNumberInterface .................................................67
Description .........................................................................67
DefaultForms .......................................................................68
RequestParameters ..................................................................68
Response ...........................................................................69
GetCertificateFromRequestInterface ....................................................71
Description .........................................................................71
DefaultForms .......................................................................72
RequestParameters ..................................................................72
Response ...........................................................................73
GetCRLInterface ......................................................................75
Description .........................................................................75
DefaultForms .......................................................................76
RequestParameters ..................................................................76
Response ...........................................................................77
ListCertificatesInterface ................................................................78
Description .........................................................................78
DefaultForms .......................................................................79
RequestParameters ..................................................................79
Response ...........................................................................84
OnlineCertificateStatusProtocolInterface.................................................87
Description .........................................................................87
DefaultForms .......................................................................87
RequestParameters ..................................................................87
Response ...........................................................................87
RenewalInterface ......................................................................88
Description .........................................................................88
DefaultForms .......................................................................88
RequestParameters ..................................................................88
Response ...........................................................................89
RevocationInterface ....................................................................89
Description .........................................................................89
DefaultForms .......................................................................90
RequestParameters ..................................................................90
Response ...........................................................................92
Chapter 4 InternationalizationofEnd-EntityInterface.............................. 95
DisplayingFormsinNon-EnglishLanguages ..............................................95

6 Netscape Certificate Management System Customization Guide • May 2002
Part 2 CustomizingAgentServicesInterface ....................................99
Chapter 5 IntroductiontoAgentServicesInterface............................... 101
AgentServicesInterface................................................................ 101
CertificateManagerAgentServices ................................................... 102
RegistrationManagerAgentServices ................................................. 103
DataRecoveryManagerAgentServices ............................................... 104
OnlineCertificateStatusManagerAgentServices....................................... 104
AccessingtheAgentServicesInterface ................................................... 105
AgentFormsandTemplates ............................................................ 106
StructureoftheAgentServicesInterface............................................... 106
LocatingAgentFormsandTemplates ................................................. 107
Chapter 6 AgentInterfaceReference........................................... 109
OverviewofAgentInterfaces ........................................................... 110
AddCAInterface ..................................................................... 112
Description ........................................................................ 112
DefaultForms...................................................................... 112
RequestParameters................................................................. 113
Response .......................................................................... 113
AddCRLInterface .................................................................... 113
Description ........................................................................ 113
DefaultForms...................................................................... 114
RequestParameters................................................................. 114
Response .......................................................................... 114
ApproveRevocationInterface .......................................................... 115
Description ........................................................................ 115
DefaultForms...................................................................... 115
RequestParameters................................................................. 115
Response .......................................................................... 117
BulkEnrollmentInterface .............................................................. 119
Description ........................................................................ 119
ConfigurationParameters ........................................................... 119
DefaultForms...................................................................... 121
RequestParameters................................................................. 121
Response .......................................................................... 126
CheckCertificateInterface.............................................................. 129
Description ........................................................................ 129
DefaultForms...................................................................... 130
RequestParameters................................................................. 130
Response .......................................................................... 130
DisplayKeyBySerialNumberInterface.................................................. 131

7
Description ........................................................................131
DefaultForms ......................................................................131
RequestParameters .................................................................131
Response ..........................................................................132
DisplayKeyForRecoveryInterface ......................................................133
Description ........................................................................133
DefaultForms ......................................................................134
RequestParameters .................................................................134
Response ..........................................................................134
ExamineRecoveryInterface.............................................................136
Description ........................................................................136
DefaultForms ......................................................................136
RequestParameters .................................................................136
Response ..........................................................................137
GetApprovalStatusInterface ...........................................................138
Description ........................................................................138
DefaultForms ......................................................................138
RequestParameters .................................................................139
Response ..........................................................................139
GetPKCS#12DataInterface ............................................................140
Description ........................................................................140
DefaultForms ......................................................................141
RequestParameters .................................................................141
Response ..........................................................................141
GrantRecoveryInterface ...............................................................142
Description ........................................................................142
DefaultForms ......................................................................142
RequestParameters .................................................................142
Response ..........................................................................143
KeyQueryInterface ...................................................................144
Description ........................................................................144
DefaultForms ......................................................................144
RequestParameters .................................................................144
Response ..........................................................................147
KeyRecoveryQueryInterface...........................................................149
Description ........................................................................149
DefaultForms ......................................................................150
RequestParameters .................................................................150
Response ..........................................................................152
ListCAInterface ......................................................................154
Description ........................................................................154
DefaultForms ......................................................................154
RequestParameters .................................................................154

8 Netscape Certificate Management System Customization Guide • May 2002
Response .......................................................................... 154
ProcessCertificateRequestInterface ..................................................... 155
Description ........................................................................ 155
DefaultForms...................................................................... 155
RequestParameters................................................................. 156
Response .......................................................................... 159
ProcessDRMRequestInterface ......................................................... 163
Description ........................................................................ 163
DefaultForms...................................................................... 164
RequestParameters................................................................. 164
Response .......................................................................... 165
ProcessRequestInterface............................................................... 167
Description ........................................................................ 167
DefaultForms...................................................................... 167
RequestParameters................................................................. 168
Response .......................................................................... 168
RecoverKeyBySerialNumberInterface ................................................. 169
Description ........................................................................ 169
DefaultForms...................................................................... 170
RequestParameters................................................................. 170
Response .......................................................................... 171
RemoveCertificateHoldInterface....................................................... 172
Description ........................................................................ 172
DefaultForms...................................................................... 173
RequestParameters................................................................. 173
Response .......................................................................... 174
RequestsQueryInterface............................................................... 175
Description ........................................................................ 175
DefaultForms...................................................................... 175
RequestParameters................................................................. 176
Response .......................................................................... 177
SelectforRevocationInterface .......................................................... 180
Description ........................................................................ 180
DefaultForms...................................................................... 180
RequestParameters................................................................. 181
Response .......................................................................... 181
UpdateCRLInterface.................................................................. 183
Description ........................................................................ 183
DefaultForms...................................................................... 183
RequestParameters................................................................. 183
Response .......................................................................... 184
UpdateDirectoryInterface ............................................................. 184
Description ........................................................................ 184

9
DefaultForms ......................................................................185
RequestParameters .................................................................185
Response ..........................................................................187
Index ....................................................................... 189

10 Netscape Certificate Management System Customization Guide • May 2002

11
About This Guide
The Customization Guide provides reference information about the HTTP interface
of Netscape Certificate Management System (CMS). The information helps you
customize Certificate Management System, and use it for issuing and managing
certificates to various end entities, such as web browsers (users), servers, Virtual
Private Network (VPN) clients, and Cisco™ routers.
This chapter has the following sections:
• What’s in This Guide (page 11)
• What You Should Already Know (page 11)
• Conventions Used in This Guide (page 12)
• Where to Go for Related Information (page 14)
What’s in This Guide
This guide covers topics that help you customize CMS agent and end-entity
interfaces. You should use this guide in conjunction with the other CMS
documentation, such as the one that explains how to install and configure
Certificate Management System. Complete list of CMS documentation is provided
later in this preface.
What You Should Already Know
This guide is intended for experienced system administrators who are planning to
deploy Certificate Management System. CMS agents should refer to CMS Agent’s
Guide for information on how to perform agent tasks, such as handling certificate
requests and revoking certificates.

Conventions Used in This Guide
12 Netscape Certificate Management System Customization Guide • May 2002
This guide assumes that you
• Are familiar with the basic concepts of public-key cryptography and the Secure
Sockets Layer (SSL) protocol.
❍SSL cipher suites
❍The purpose of and major steps in the SSL handshake
• Understand the concepts of intranet, extranet, and the Internet security and the
role of digital certificates in a secure enterprise. These include the following
topics:
❍Encryption and decryption
❍Public keys, private keys, and symmetric keys
❍Significance of key lengths
❍Digital signatures
❍Digital certificates, including various types of digital certificates
❍The role of digital certificates in a public-key infrastructure (PKI)
❍Certificate hierarchies
If you are new to these concepts, we recommend that you read the
security-related appendixes (Appendix D and Appendix E) of the
accompanying manual, Managing Servers with Netscape Console.
• Are familiar with the role of Netscape Console in managing Netscape servers.
Otherwise, see the accompanying manual, Managing Servers with Netscape
Console.
• Are reading this guide in conjunction with the documentation listed in “Where
to Go for Related Information” on page 14.
Conventions Used in This Guide
The following conventions are used in this guide:
•Monospaced font—Thistypefaceisusedforanytextthatappearsonthe
computer screen or text that you should type. It’s also used for filenames,
functions, and examples.
Example: Server Root is the directory where the CMS binaries are kept.
•Italic—Italic type is used for emphasis, book titles, and glossary terms.

Conventions Used in This Guide
About This Guide 13
Example: This control depends on the access permissions the superadministrator
has set up for you.
• Text within “quotation marks”—Cross-references to other topics within this
guide.
Example: For more information, see “Issuing a Certificate to a New User” on
page 154.
•Boldface—Boldface type is used for various UI components such as captions
and field names, and the terminology explained in the glossary, which can be
found in CMS Installation and Setup Guide.
Example:
Rotation frequency. From the drop-down list, select the interval at which the
server should rotate the active error log file. The available choices are Hourly,
Daily, Weekly, Monthly, and Yearly. The default selection is Monthly.
•Monospaced [ ]—Square brackets enclose commands that are optional.
Example:
PrettyPrintCert <input_file> [<output_file>]
<input_file> specifies the path to the file that contains the base-64
encoded certificate.
<output_file> specifies the path to the file to write the certificate. This
argument is optional; if you don’t specify an output file, the certificate
information is written to the standard output.
• <>—Angle brackets enclose variables or placeholders. When following
examples, replace the angle brackets and their text with text that applies to
your situation. For example, when path names appear in angle brackets,
substitute the path names used on your computer.
Example: Using Netscape Communicator 4.7x or later, enter the URL for the
administration server: http://<hostname>:<port_number>
• /—A slash is used to separate directories in a path. If you use the Windows NT
operating system, you should replace / with \ in paths.
Example: Except for the Security Module Database Tool, you can find all the
other command-line utilities at this location: <server_root>/bin/cert/tools
• Sidebar text—Sidebar text marks important information. Make sure you read
the information before continuing with a task.
Examples:

WheretoGoforRelatedInformation
14 Netscape Certificate Management System Customization Guide • May 2002
Where to Go for Related Information
This section summarizes the documentation that ships with Certificate
Management System, using these conventions:
•<server_root> is the directory where the CMS binaries are kept (which you
specify during installation).
•<instance_id> is the ID for this instance of Netscape Certificate Management
System (specified during installation).
The documentation set for Certificate Management System includes the following:
•Managing Servers with Netscape Console
Provides background information on basic cryptography concepts and the role
of Netscape Console. To view the HTML version of this guide, open this file:
<server_root>/manual/en/admin/ag/contents.htm
•CMS Installation and Setup Guide
Describes how to plan for, install, and administer Certificate Management
System. To access the installation and configuration information from within
the CMS Installation Wizard or from the CMS window (within Netscape
Console), click any help button. To view the HTML version of this guide, open
this file: <server_root>/manual/en/cert/setup_guide/contents.htm
•CMS Plug-Ins Guide
Provides detailed reference information on CMS plug-in modules. To access
this information from the CMS window within Netscape Console, click any
help button. To view the HTML version of this guide, open this file:
<server_root>/manual/en/cert/plugin_guide/contents.htm
NOTE You can use Netscape Console only when Netscape Administration
Server is up and running.
CAUTION A caution note documents a potential risk of losing data, damaging
software or hardware, or otherwise disrupting system performance.

Where to Go for Related Information
About This Guide 15
•CMS Command-Line Tools Guide
Provides detailed reference information on CMS tools. To view the HTML
version of this guide, open this file:
<server_root>/manual/en/cert/tools_guide/contents.htm
•CMS Customization Guide (this guide)
Provides detailed reference information on customizing the end-entity and
agent interfaces. To view the HTML version of this guide, open this file:
<server_root>/manual/en/cert/custom_guide/contents.htm
•CMSAgent’sGuide
Provides detailed reference information on CMS agent interfaces. To access
this information from the Agent Services pages, click any help button. To view
the HTML version of this guide, open this file:
<server_root>/cert-<instance_id>/web-apps/agent/manual/
agent_guide/contents.htm
•End-EntityHelp
Provides detailed reference information on CMS end-entity interfaces. To
access this information from the end-entity pages, click any help button. To
view the HTML version of this guide, open this file:
<server_root>/cert-<instance_id>/web-apps/ee/manual/ee_guide/
contents.htm
For a complete list of CMS documentation, open the
<server_root>/manual/index.html file. For the latest information about
Certificate Management System, check the CMS Release Notes and other
documents available at this site:
http://enterprise.netscape.com/docs/cms/index.html

WheretoGoforRelatedInformation
16 Netscape Certificate Management System Customization Guide • May 2002

17
Chapter 1
Before You Begin
The services interfaces that come with Netscape Certificate Management System
(CMS) make it possible for end-entities and agents to interact with the server. Your
end-entities and agents can use the interface’s HTML-based forms to carry out
various certificate and key-related operations, such as enrolling for, renewing, and
revoking certificates.
You can use the default forms as they are, customize them, or develop your own
forms to suit your organization’s policies or terminology. This chapter explains
how to customize the forms and templates used by the interfaces.
The chapter has the following sections:
• What You Need to Know to Change Forms (page 17)
• HowtheFormsWork(page18)
• JavaScript Used By All Interfaces (page 22)
• How to Register Servlets (page 26)
What You Need to Know to Change Forms
Changing the default forms’ appearance requires only a basic knowledge of HTML
and a text editor. However, more significant customizing efforts require a good
understanding of the following:
• HTTP, Query URLs, and HTML Forms
•JavaScript
• The way the End-Entity Services Interface works

How the Forms Work
18 Netscape Certificate Management System Customization Guide • May 2002
HTTP, Query URLs, and HTML Forms
Requests from the end-entity services interface to Certificate Management System
are submitted using the HTTP GET and POST methods. Requests take the form of
query URLs (in the case of the GET method) or data sent through standard output
(in the case of the POST method).
For background on these topics, consult books on authoring for the World Wide
Web, on HTML, and on the HTML specification. Another good source is
Netscape’s documentation on creating Internet sites; that documentation is
available at this URL:
http://home.netscape.com/assist/net_sites/index.html
JavaScript
JavaScript is a scripting language that most browser software, including Netscape
Navigator and Communicator, used for dynamic forms. (JavaScript is not the same
as the more sophisticated and powerful Java language that is also supported by
Netscape clients.)
In the agent and end-entity services forms, JavaScript is used to check input values
and to formulate requests to the CMS server. JavaScript is also used in the output
templates to present and format responses from the CMS server.
To customize the forms and templates, you need to be familiar with JavaScript. For
more information on JavaScript and its use in Netscape browsers, see the Netscape
JavaScript Authoring Guide available at this URL:
http://home.netscape.com/eng/mozilla/3.0/handbook/javascript/
index.html
There are also several books on this topic.
How the Forms Work
Administrators, end-entities, and agents request service operations using the HTTP
or HTTPS (HTTP over SSL) protocol using either the GET method (by submitting
query URLs) or the POST method (by submitting a URL-encoded form with the
content-type application/x-www-form-urlencoded). The GET method and the
POST method result in a set of name-value pairs; this set constitutes the request.
For certificate service operations, the URI portion should indicate
/<operation>

How the Forms Work
Chapter 1 Before You Begin 19
where operation designates the certificate (management) service portion, such as
enrollment, retrieval, renewal, or revocation of the CMS server. Any HTTP
operationswithURIsthatdonotbeginwiththe/<operation> prefix are treated as
requests for other kinds of web service by the CMS server. See chapters Chapter 3,
“End-Entity Interface Reference” and Chapter 6, “Agent Interface Reference” for
details on all the available operations.
Requests Sent to the CMS server
The services interface handles a set of operations. Each operation has a name and
expects a specific set of parameters.
(The examples in this chapter are what you would see if Certificate Management
System were running on the host certs.example.com and listening on the
standard HTTPS port.)
Forexample,thedisplayBySerial interface displays the certificate with the serial
number matching the serialNumber parameter. To use the displayBySerial
interface to retrieve the certificate with serial number 58 (0x3a) using HTTP GET,
you would use the following URL:
https://certs.example.com/displayBySerial?serialNumber=58
You could embed this URL in a link on an HTML page to allow users to view this
certificate.
If you used an HTML form (rather than a query URL) to invoke this operation, the
HTML for the form might look like this:
<FORM ACTION="https://certs.example.com/displayBySerial"
METHOD="POST">
Serial Number: <INPUT TYPE="TEXT" NAME="serialNumber">
<INPUT TYPE="SUBMIT" VALUE="Display This Certificate">
</FORM>
In the resulting form, the user enters the serial number of the certificate to be
displayed.
Responses and Output Templates
Certificate Management System responds to service requests by sending back an
HTML page built from two parts: a fragment of JavaScript code containing the data
resulting from the operation and a template defining how the data is processed and
displayed.

How the Forms Work
20 Netscape Certificate Management System Customization Guide • May 2002
The fragment of JavaScript code consists of a result object that contains data
properties only (no methods). The properties of the object correspond to parts of
the response.
The template generally contains a combination of HTML and JavaScript code that
processes and displays data. The template is set up to make use of the data in the
result object.
In responding to a request, Certificate Management System determines the data
that needs to be returned, embeds the data in the definition of the result object,
and inserts the result object in the template. When the browser receives the
constructed HTML page from the CMS server, the JavaScript code in the template
file looks at the values in the result object and uses the data to display the HTML
page to the user.
Because the functions that manipulate and display the data are accessible to you in
the plain-text template files (as opposed to being hardcoded in the CMS server’s
libraries), you can customize the way data is used and presented to the user by
editing the JavaScript and HTML in the template files.
Forexample,thedisplayBySerial operation generates the following JavaScript
code fragment:
<SCRIPT LANGUAGE="JavaScript">
var header = new Object();
var fixed = new Object();
var recordSet = new Array;
var result = new Object();
var httpParamsCount = 0;
var httpHeadersCount = 0;
var authTokenCount = 0;
var serverAttrsCount = 0;
header.HTTP_PARAMS = new Array;
header.HTTP_HEADERS = new Array;
header.AUTH_TOKEN = new Array;
header.SERVER_ATTRS = new Array;
header.certPrettyPrint = [long string containing pretty-printed
certificate]
header.noCertImport = false;
header.certFingerprint = [string containing certificate
fingerprints]
header.authorityid = "ca";
header.serialNumber = 5;
header.emailCert = true;
header.certChainBase64 = [string containing base-64 encoded
certificate]