Complete Contents
About This Guide
PART 1: Netscape Certificate Management System
Chapter 1: Introduction to Certificate Management System
Chapter 2: Administration Tasks and Tool
Chapter 3: Configuration
PART 2: Managing Certificate Management System
Chapter 4: Installing and Uninstalling Instances
Chapter 5: Starting and Stopping Instances
PART 3: System-Level Configuration
Chapter 6: Configuring Ports, Database, and SMTP Settings
Chapter 7: Managing Privileged Users and Groups
Chapter 8: Keys and Certificates
PART 4: Authentication
Chapter 9: Introduction to Authentication
Chapter 10: Using the PIN Generator Tool
Chapter 11: Configuring Authentication for End Entities
Chapter 12: Developing Authentication Plug-ins
PART 5: Job Scheduling and Notification
Chapter 13: Introduction to Job Scheduling and Notifications
Chapter 14: Configuring Jobs
PART 6: Policies
Chapter 15: Introduction to Policies
Chapter 16: Configuring Policies
PART 7: LDAP Publishing
Chapter 17: Introduction to LDAP Publishing
Chapter 18: Configuring Subsystems for LDAP Publishing
Chapter 19: Publishing CRLs
PART 8: Agent and End-Entity Interfaces
Chapter 20: Introduction to End-Entity and Agent Interfaces
Chapter 21: Customizing End-Entity and Agent Interfaces
PART 9: Logs
Chapter 22: Introduction to Logs
Chapter 23: Managing Logs
PART 10: Issuance and Management of End-Entity Certificates
Chapter 24: Issuing and Managing End-Entity Certificates
Chapter 25: Recovering Encrypted Data
PART 11: Appendixes
Appendix A: Distinguished Names
Appendix B: Backing Up and Restoring Data
Appendix C: Command-Line Utilities
Appendix D: Certificate Database Tool
Appendix E: Key Database Tool
Appendix F: Netscape Signing Tool
Appendix G: SSL Strength Tool
Appendix H: SSL Debugging Tool
Previous Next Contents Index Bookshelf


Chapter 21 Customizing End-Entity and Agent Interfaces

The end-entity registration services interface that comes with Netscape Certificate Management System (CMS) makes it possible for end entities to interact with the server. Your end entities can use the interface's HTML-based forms to carry out various certificate and key-related operations: enroll for a certificate; and renew and revoke their 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 the forms included in the end-entity services interface work and how to customize them.

 The chapter has the following sections:
What You Need to Know
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

Requests from the end-entity services interface to Certificate Management System are submitted using the HTTP GET and POST methods. These 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 the authoring for the World Wide Web, HTML, and the HTML specification. Another good source is Netscape's documentation on creating net sites, available at this URL:

http://home.netscape.com/assist/net_sites/index.html

 JavaScript

JavaScript is a simple, lightweight scripting language that most browser software, including Netscape Navigator and Communicator, use for dynamic forms. (JavaScript should not be confused with the more sophisticated and powerful Java language that is also supported by Netscape clients.)

In the end-entity services forms, JavaScript is used to check input values and to formulate requests to the server. JavaScript is also used in the output templates to present and format responses from the 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
Certificate Management System provides both normal web service and certificate service operations.

 Certificate service operations are requested using the HTTP and HTTPS (HTTP over SSL) protocol using the GET method with query URLs or the POST method with URL-encoded form submissions (with the usual content-type application/x-www-form-urlencoded). In either case, the submission results in a set of named attribute-value pairs that constitutes the request.

 For certificate service operations, the URI portion should indicate

/<operation>

where operation designates the certificate (management) service portion, such as enrollment, retrieval, renewal, or revocation of the server. Any HTTP operations with URIs that do not begin with the /<operation> prefix are treated as requests for other kinds of web service by the server.

Requests Sent to the Server

The end-entity services interface consists of a set of operations. Each operation has a name and expects a specific set of named parameters.

Each certificate service operation must contain the attribute op in the submission. The op attribute identifies the specific certificate service operation that is being requested. Each operation has required and optional parameters that must be included among the remaining attributes and values in the submission. The parameters used by a given operation are specific to that operation.

(The examples in this chapter assume that Certificate Management System is running on the host certs.mydom.com and is listening on the standard HTTPS port.)

The following example illustrates a sample request sent through the certificate service interface. This request executes the displayBySerial operation, which displays a certificate with a given serial number. The displayBySerial operation uses a single required input parameter, serialNumber. This parameter is the serial number of the certificate to be displayed.

 The following URL uses the GET method to invoke the displayBySerial operation on the Certificate Management System. The operation displays the certificate with the hexadecimal serial number 3a (or 58, in decimal). 

https://certs.mydom.com/cms?op=displayBySerial&serialNumber=0x3a

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 form might look like this:

<FORM ACTION="https://certs.mydom.com/cms" METHOD="POST">

<INPUT TYPE="HIDDEN" NAME="op" VALUE="displayBySerial">

Serial Number: <INPUT TYPE="TEXT" NAME="serialNumber">

<INPUT TYPE="SUBMIT" VALUE="Display This Certificate">

</FORM>

In this form-based version, the user can enter the serial number of the certificate to be displayed.

 Responses and Output Templates

Certificate Management System responds to certificate 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.

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 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 display and manipulate the data are accessible to you in the plain-text template files (as opposed to being hardcoded in the 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.

 For example, the displayBySerial operation generates the following JavaScript code fragment:

<SCRIPT LANGUAGE="JavaScript">

var header = new Object();

var result = new Object();

header.certPrettyPrint = [long string containing pretty- printed certificate]

header.certChainBase64 = [string containing base64-encoded certificate]

header.serviceURL = "https://tahoma.mcom.com/cms";

header.serialNumber = 2;

result.header = header;

</SCRIPT>

Notice how this code fragment defines an object named result and puts the resulting data from the operation in the properties of that object. Each certificate service operation returns an object named result. The contents of the result object are specific to the operation.

When it responds to the request, Certificate Management System inserts this JavaScript fragment into the template file for the displayBySerial operation. The server inserts the fragment in the position in the template file where it finds the server-parsed tag <CMS_TEMPLATE>. It then returns the completed template with the inserted fragment to the client. The client then processes the completed template and displays the resulting page. In the case of the displayBySerial operation, the template file uses JavaScript and HTML to display the contents of the result object to the user.

 Because the data from the operation is available in the result object, you can customize the JavaScript in the template or write your own functions to use this data. For example, to access the certificate's serial number, you can write a JavaScript function that uses result.header.serialNumber.

Templates for each operation are stored in the forms subdirectory of the server instance. Each operation has a corresponding template file in this directory. The template filename is as follows:

 <operation>.template

<operation> is the name of the operation. For example, the template file for the displayBySerial operation is displayBySerial.template.

Important Be careful not to confuse the forms directory for the server instance (<server_root>/cert-<instance_id>/web) with the distribution-source forms directory (<server_root>/bin/cert/forms). You should edit the forms for a server instance only. Do not edit the source forms in the <server_root>/bin/cms/forms directory.

The server reads the templates dynamically; you do not have to restart the server for it to read any changes to the template files.

Errors and the Error Template

All certificate service errors in the end-entity interface are returned through a single template called GenError.template. The error result object contains the following data properties:

<SCRIPT LANGUAGE="JavaScript">

var header = new Object();

var result = new Object();

header.errorDetails = [ a string describing the context of the error ]

header.errorDescription = [ a string describing the error ]

result.header = header;

</SCRIPT>

The error template included in the distribution prints the information in the error result object along with some explanatory text.
Summary of End-Entity Forms and Templates
This section gives the location of the default forms that appear in the end-entity services interface and lists the forms by type of end-entity operation. Figure 21.1 shows the end-entity interface of a Registration Manager.

The end-entity services interface is divided into three parts or frames--top, menu, and content. The top frame includes tabs that are specific to end-entity operations, such as certificate enrollments and renewals. The menu lists all the operations supported by the selected tab. The content shows the form pertaining to the operation an end entity chooses in the menu; the form contains information to carry out the selected operation.

Figure 21.1 End-entity services interface

Locating End-Entity Forms and Templates

You can find the HTML forms specific to end-entity operations and the corresponding output templates at this location:

<server_root>/cert-<instance_id>/web/ee/...

<server_root> is the directory where the CMS binaries are kept. You first specified this directory during installation.

<instance_id> is the ID for this instance of Certificate Management System. You first specified this during installation.

Forms for Certificate Enrollment

Table 21.1 lists the forms that correspond to the menu options in the Enrollment tab of the end-entity services interface.

Table 21.1 Default forms for end-entity enrollment

Menu link and form filename
Description
User Enrollment (lists menu options for end-user enrollment)
Manual
(ManUserEnroll.html)
End users can use this form to request SSL client and
S/MIME certificates. Both the Certificate Manager and Registration Manager provide this form.

Directory Based
(DirUserEnroll.html)

End users can use this form to request SSL client and
S/MIME certificates. Both the Certificate Manager and Registration Manager provide this form.

Directory and PIN Based (DirPinUserEnroll.html)
End users can use this form to request SSL client and
S/MIME certificates. Both the Certificate Manager and Registration Manager provide this form.

Server Enrollment (lists menu options for server enrollment)
Manual
(ManServerEnroll.html)
Server administrators can use this form to request SSL server certificates for servers. Both the Certificate Manager and Registration Manager provide this form.

Directory Based
(DirServerEnroll.html)

Server administrators can use this form to request SSL server certificates for servers. Both the Certificate Manager and Registration Manager provide this form.

This form is not used in the default interface.

Registration Manager Enrollment (lists menu options for Registration Manager enrollment)
Manual
(ManRAEnroll.html)

Registration Manager administrators can use this form to request a signing certificate for a Registration Manager. For details about this certificate, see "Signing Key Pair and Certificate".

Both the Certificate Manager and Registration Manager provide this form.

Certificate Manager Enrollment (lists menu options for Certificate Manager enrollment)
Manual
(ManCAEnroll.html)

Certificate Manager administrators can use this form to request CA signing certificates for Certificate Managers functioning as subordinate CAs. For details about the CA signing certificate, see "CA Signing Key Pair and Certificate".

Only the Certificate Manager provides this form.

Object Signing Enrollment (lists menu options for object signing enrollment)
Manual
(ManObjSignEnroll.html)

End users and administrators can use this form to enroll for a certificate that allows them to sign objects, such as Java applets. Both the Certificate Manager and Registration Manager provide this form.

Forms for Certificate Renewal

Table 21.2 lists the forms that correspond to the menu options in the Renewal tab of the end-entity services interface.

Table 21.2 Default forms for certificate renewal

Menu link and form filename
Description
Server Certificate
(ServerRenewal.html)

Server administrators can use this form to renew server certificates. Both the Certificate Manager and Registration Manager provide this form.

This form is not used in the default interface.

User Certificate
(UserRenewal.html)

End users can use this form to renew their SSL client and S?MIME certificates; users can renew their
S/MIME certificates, only if these certificates were issued with the SSL client bit set. Both the Certificate Manager and Registration Manager provide this form.

Forms for Certificate Revocation

Table 21.3 lists the forms that correspond to the menu options in the Revocation tab of the end-entity services interface.

Table 21.3 Default forms for certificate revocation

Menu link and form filename
Description
Server Revocation (ServerRevocation.html)

Server administrators can use this form to revoke server certificates. Both the Certificate Manager and Registration Manager provide this form.

This form is not used in the default interface.

User Revocation (UserRevocation.html)
End users can use this form to revoke their SSL client certificates. Both the Certificate Manager and Registration Manager provide this form.

Forms for Certificate Retrieval

Table 21.4 lists the forms that correspond to the menu options in the Retrieval tab of the end-entity services interface.

Table 21.4 Default forms provided for certificate retrieval

Menu link and form filename
Description
List Certificates
(queryBySerial.html)

End users and administrators can use this form to list certificates based on their serial numbers. Only the Certificate Manager provides this form.

Search for Certificates
(queryCert.html)

End users and administrators can use this form to search for specific certificates. The search criteria can be a combination of the following:

Only the Certificate Manager provides this form.

Import CA Certificate Chain (GetCAChain.html)
End users and administrators can use this form to import the certificate chain of a Certificate Manager (CA) into their browsers or servers. They can

Both the Certificate Manager and Registration Manager provide this form.

Import Certificate Revocation List
(DisplayCRL.html)

End users and administrators can use this form to:

Only the Certificate Manager provides this form.

Forms for Key Recovery

Table 21.5 lists the forms that correspond to the menu options in the Recovery tab of the end-entity services interface.

Table 21.5 Default forms for encryption private key recovery

Menu link and form filename
Description
Key Recovery
(KeyRecovery.html)
End users can use this form to retrieve their encryption private keys from the Data Recovery Manager. Both the Certificate Manager and Registration Manager provide this form, if you configure them to function as trusted managers to a Data Recovery Manager.

Note that end-user initiated key recovery is not supported in this version of the software. The form is not used in the default interface.

Other Forms

Table 21.5 lists common forms that are used by the operation-specific forms in the end-entity services interface.

Table 21.6 Default forms for encryption private key recovery

Form filename
Description
enrollMenu.html
This file loads and highlights the Enrollment tab.

renewalMenu.html
This file loads and highlights the Renewal tab.

recoveryMenu.html
This file loads and highlights the Recovery tab.

retrievalMenu.html
This file loads and highlights the Retrieval tab.

index.html
This file contains the menu options. To change the name of an option, search for it in the file and then edit it.

*.js
Files with a .js file extension include JavaScript helper functions that are used by all the other forms provided for end entities.

xenroll.dll
This file enables the end user enrollment forms to work with Microsoft Internet Explorer.

Output Templates for End-Entity Operations

Table 21.7 lists the default templates that are displayed when a user performs a certificate operation. For example, when searching for certificates.

Table 21.7 Summary of default templates for the end-entity services interface

Template filename
Description
displayBySerial.template

Used to display information pertaining to a certificate when users view an individual certificate (for example, when they click the Details button next to a certificate).

EnrollSuccess.template

Used to inform the CMS administrator that the agent certificate he or she requested has been successfully installed in the subsystem's internal database.

GenError.template

Used to display an error message to the user when an error occurs.

GenPending.template

Used to inform the user that the certificate request he or she submitted has been queued for agent approval.

GenRejected.template

Used to inform the user that the certificate request he or she submitted has been rejected by the server.

GenSuccess.template

Used to inform the user that the certificate request he or she submitted has been approved by the server.

GenSvcPending.template

Used to inform the user that the certificate request he or she submitted has been queued for agent approval.

GenUnauthorized.template

Used to inform the user that he or she performed an authorized operation.

GenUnexpectedError.template

Used to inform the user that the server encountered an unexpected error while processing the request she or he submitted.

ImportCert.template

Used to display the CA certificate when users attempt to import the CA certificate.

queryCert.template

Used to display the list of certificates when users search for certificates.

RenewalSuccess

Used to inform the user that the certificate she or he submitted for renewal has been successfully renewed.

RevocationSuccess

Used to inform the user that the certificate she or he submitted for revocation has been revoked.


Summary of Agent Forms and Templates
This section describes the Agent Services interface, gives the location of the agent forms and output templates, and lists all of the default forms and templates.

 Structure of the Agent Services Interface

As shown in Figure 21.2, the Agent Services interface is divided into three parts or frames--top, menu, and content. The top frame includes the tabs that allow you to select a subsystem. The menu lists all the operations supported by the selected subsystem. The content shows the form pertaining to the operation an agent chooses in the menu; the form contains information to carry out the selected operation.

Figure 21.2 Various parts of the Agent Services interface

Locating Agent Forms and Templates

You can find the HTML forms specific to agent operations and the corresponding output templates at this location:

<server_root>/cert-<instance_id>/web/agent/<subsystem>/...

<server_root> is the directory where the CMS binaries are kept. You first specified this directory during installation.

<instance_id> is the ID for this instance of Certificate Management System. You first specified this during installation.

<subsystem> refers to the forms directory pertaining to a subsystem, the Certificate Manager (ca), Registration Manager (ra), or Data Recovery Manager (kra).

 

© Copyright 1999 Netscape Communications Corp., a subsidiary of America Online, Inc. All rights reserved.