Chapter 1   Before You Begin


The services interfaces that come with iPlanet 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

• How the Forms Work

• JavaScript Used By All Interfaces

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

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>

where operation designates the certificate (management) service portion, such as enrollment, retrieval, renewal, or revocation of the CMS 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 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.siroe.com and listening on the standard HTTPS port.)

For example, the displayBySerial 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.siroe.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.siroe.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.

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.

For example, the displayBySerial 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]
result.header = header;
result.fixed = fixed;
result.recordSet = recordSet;
</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, the displayBySerial interface running on Certificate Management System inserts this JavaScript fragment into the template file it uses to return results to the requestor. the CMS server inserts the fragment in the template file where it finds the tag <CMS_TEMPLATE>. It then returns the 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 web subdirectory of the CMS server instance. The web subdirectory contains the following subdirectories where forms and templates are located:

• ee for end-entity interfaces

• agent/ca for Certificate Manager agent interfaces

• agent/kra for Data Recovery Manager agent interfaces

• agent/ra for Registration Manager agent interfaces

the CMS server reads the templates dynamically; you do not have to restart the CMS server for it to read 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 default CMS error template prints the information in the error result object along with some explanatory text.

JavaScript Used By All Interfaces

---

This section describes the JavaScript variables that are common to all responses from end-entity and agent interfaces. The interface definitions in subsequent sections give details about additional JavaScript that may be added by specific interfaces.

The CMS server handling the interface request replaces the <CMS_TEMPLATE> tag in a template with the JavaScript variables described in this section. When you modify or create templates, make sure the <CMS_TEMPLATE> tag appears in the file if your response needs to use any of the variables returned by an interface.

The JavaScript included in a response allows you to customize how the response is displayed or processed. For example, the queryCert.template file is used to list certificates returned by the List Certificates interface. The template makes extensive use of the JavaScript in the response to display a summary of each certificate and also to create new HTTP forms that can show details about a certificate.

All responses will include the following JavaScript:

<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;
fixed.preserved = "foo";
var recordCount = 0;
var record;
record = new Object;
record.HTTP_PARAMS = new Array;
record.HTTP_HEADERS = new Array;
record.AUTH_TOKEN = new Array;
record.SERVER_ATTRS = new Array;
recordSet[recordCount++] = record;
result.header = header;
result.fixed = fixed;
result.recordSet = recordSet;
</SCRIPT>

On its own, the base JavaScript is not very useful. Data pertinent to the response is added to this framework by the interface that creates the response. For example, an interface that lists a certificate might add the base-64 encoding of the certificate to the record object.

The result object contains most of the useful data, including the header object, the fixed object, and the recordSet array. Responses will usually add relevant data to one of these components of the result object. The purpose of these components can be summarized as follows:

• The header object contains variables and data that apply generally to all parts of the response. For example, a response including several certificates would store the total number of certificates returned in the header, while individual certificate data would be stored in recordSet elements. Variables in the header are accessed as result.header.variableName.

• The fixed object contains information that is fixed and independent of the data being returned in the response. Such data includes the hostname and port of the CMS server that handled the request, which is useful for creating HTTP forms that use the server and port that generated the response. Variables in the fixed object are accessed as result.fixed.variableName.

• The recordSet array is available to any response that returns certificates. Data for each certificate is returned in variables in a record object. Each record object is then added to the recordSet array. Variables in a particular record object are accessed by an index into the recordSet array: result.recordSet[i].variableName.

The following table describes the format an purpose of all the data included in the base <CMS_TEMPLATE> JavaScript:

Table 1-1    Variables Returned by the Base JavaScript  

Variable	Format/Type and Description
AUTH_TOKEN	array Each element in this array is a name-value pair. These pairs represent variables that were returned from an authentication plug-in used (internally) by the interface. For example, if the authentication plug-in returned variables fooValid and barValid indicating whether the foo and bar parameters of a request were valid, the JavaScript in the response might look like: header.AUTH_TOKEN[0].name = "fooValid"; header.AUTH_TOKEN[0].value = "false"; header.AUTH_TOKEN[1].name = "barValid"; header.AUTH_TOKEN[1].value = "true"; These values are created when an authentication plug-in invokes set(nameSrting, valueString) on an AuthToken object.
authTokenCount	number The number of AUTH_TOKEN objects returned in this response.
fixed	object An object for containing data that is constant, such as the hostname, port number, or ID number associated with a request.
header	object An object for containing data that applies to the entire response, such as the number of records or the LDAP query that was used to get the data.
HTTP_HEADERS	Array Each element in this array is a name-value pair. These pairs represent HTTP request headers sent from the client to the interface. Use the CMS.cfg parameter saveHttpHeaders to list HTTP header values that should be saved and returned in responses. For example, if saveHttpHeaders is set to "accept-language, user-agent", the JavaScript in the response might look like: header.HTTP_HEADERS[0].name = "accept-language" header.HTTP_HEADERS[0].value = "en"; header.HTTP_HEADERS[1].name = "user-agent" header.HTTP_HEADERS[1].value = "Mozilla/4.51 (X11; U; SunOS 5.7 sun4u)"; The default value for saveHttpHeaders (if it is not explicitly set in CMS.cfg) is "accept-language, user-agent".
httpHeadersCount	number The number of HTTP_HEADERS objects returned in this response.
HTTP_PARAMS	Array Each element in this array is a name-value pair. These pairs represent variables and their values that were used in the HTTP request made to the interface. Some HTTP parameters will be discarded after the request has been authenticated so that sensitive data is not stored on the CMS server. By default, parameters named pwd, password, and passwd are discarded after authentication. All other parameters are passed back in the response. Use the CMS.cfg parameter dontSaveHttpParams to list parameters that should be discarded by the CMS server after authentication. For example, if dontSaveHttpParams is set to "pwd" and the request used parameters named uid and pwd, the JavaScript in the response might look like: header.HTTP_PARAMS[0].name = "uid" header.HTTP_PARAMS[0].value = "userOne"; The default value for dontSaveHttpParams (if it is not explicitly set in CMS.cfg) is "pwd, password, passwd".
httpParamsCount	number The number of HTTP_PARAMS objects returned in this response.
fixed.preserved	any data This variable contains the value of the parameter named preserved passed to the interface. It allows any data to be passed through from a request to the response template by submitting a parameter named preserved in the request.
record	Object An object for containing data about a single certificate. Variables and values are added to a record object, then the record object is added as an element in the recordSet array.
recordCount	number The number of record objects returned in this response. Usually this is incremented for each record added to the recordSet array. For example, recordCount = 0; record.serialNumber = 1; recordSet[recordCount++] = record; record.serialNumber = 2; recordSet[recordCount++] = record;
recordSet	Array This array contains any number of record objects. The base JavaScript will also add recordSet to the result object, so use result.recordSet[i].variableName to access individual fields of a given recordSet element.
result	Object The primary container for all of the results returned in this template. The fixed, header, and recordSet objects are added to the result object as the last statements in the base JavaScript.
SERVER_ATTRS	Array Each element in this array is a name-value pair. These pairs represent variables and their values that were added by modules internal to the CMS serever or policy plug-ins. For example, if a policy plug-in added a variable called requestStatus with a value of pending, the resulting JavaScript might be: header.SERVER_ATTRS[0].name = "requestStatus"; header.SERVER_ATTRS[0].value = "pending";
serverAttrsCount	number The number of SERVER_ATTRS objects returned in this response.