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 CMS Instances
Chapter 5: Starting and Stopping CMS 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: Authentication Modules for End-Entity Enrollment
Chapter 11: Using the PIN Generator Tool
Chapter 12: Configuring Authentication for End Users
Chapter 13: Developing Custom Authentication Modules
PART 5: Job Scheduling and Notification
Chapter 14: Introduction to Job Scheduling and Notifications
Chapter 15: Configuring Schedulable Jobs
PART 6: Policies
Chapter 16: Introduction to Policy
Chapter 17: Constraints-Specific Policy Modules
Chapter 18: Extension-Specific Policy Modules
Chapter 19: Configuring a Subsystem's Policies
PART 7: Publishing
Chapter 20: Introduction to Publishing Certificates and CRLs
Chapter 21: Modules for Publishing Certificates and CRLs
Chapter 22: Configuring a Certificate Manager for Publishing
PART 8: Agent and End-Entity Interfaces
Chapter 23: Introduction to End-Entity and Agent Interfaces
Chapter 24: Customizing End-Entity and Agent Interfaces
PART 9: Logs
Chapter 25: Introduction to Logs
Chapter 26: Managing Logs
PART 10: Issuance and Management of End-Entity Certificates
Chapter 27: Issuing and Managing End-Entity Certificates
Chapter 28: 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
Netscape Certificate Management System Administrator's Guide: Customizing End-Entity and Agent
Previous Next Contents Index Bookshelf


Chapter 24 Customizing End-Entity and Agent Interfaces

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
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. 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 the sections End-entity Interface Reference and 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.mydom.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.mydom.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.mydom.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:

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.


Displaying Forms in Non-English Languages
The forms and response templates that come with Certificate Management System are all in English. Certificate Management System supports forms and templates in other languages, and multiple languages can be supported on the same CMS server instance. Every aspect of the CMS server is designed to accomodate multiple languages, including all storage and certificate processing (it is possible to have certificate subject names with data in Chinese, for example). The CMS administration console windows support data in non-English languages, but the messages and menu items cannot be localized.

When an HTTP or HTTPS request arrives at the CMS server, the CMS server checks the HTTP Accept-language header to see what languages are preferred by the requestor. For example, a client that prefers content in Korean would have the value "ko" in the Accept-language header. The server looks in the directory where the default form would be stored to see if there is a directory matching the first value in the Accept-language header. If there is such a directory, the CMS server looks for the correct form or template in the language-specific directory; if the form or template is not found, the default is still used.

For example, the manual user enrollment form is ManUserEnroll.html. It is stored in the web/ee/ directory below the CMS server root. If you wanted to provide a version of this form in French and German for your users, you would translate the form, create the directories web/ee/fr (French) and web/ee/de (German), and put the translated versions of the form in the appropriate, language-specific subdirectory. The appropriate form is sent to users automatically based on the language preferences set in their browsers.

Localized versions of the agent forms and templates are supported in the same way. Create language-specific subdirectories of web/agent/ca, web/agent/kra, and web/agent/ra to provide forms and templates for agents in non-English languages.

Note that if a browser sends more than one language, the CMS server will try to match one of the browser's language preferences with the default locale of the system where the server is running. If no match is found, the default page in English will be returned to the browser. Users having trouble accessing your localized content should make sure they have only one language set in their browsers.

Certificate Management System uses a default character set for each language (see Table 24.1). If you want to use a different character set for a language, you must edit the CMS server configuration file CMS.cfg and add a line with the following format:

i18nCharset.<lang>=<charset>

Where <lang> is the two-letter code for the language (the same as the directory where the localized files are stored) and <charset> is the character set to use with files in that language. For example, to use a character set named EUC_KR for Korean-language (ko) content, add the following line to CMS.cfg:

i18nCharset.ko=EUC_KR

The following table lists the languages supported by Certificate Management System, the two-letter language code to use for language-specific directories, and the default character set Certificate Management System uses for the language:

Table 24.1 Languages and Default Character Sets

Language
Code
Character set
Language
Code
Character set
Albanian
sq
ISO-8859-2
Arabic
ar
ISO-8859-6
Bulgarian
bg
ISO-8859-5
Byelorussian
be
ISO-8859-5
Catalan (Spanish)
ca
ISO-8859-1
Chinese (Simplified/Mainland)
zh
GB2312
Chinese (Traditional/Taiwan)
zh
Big5
Croatian
hr
ISO-8859-2
Czech
cs
ISO-8859-2
Danish
da
ISO-8859-1
Dutch
nl
ISO-8859-1
English
en
ISO-8859-1
Estonian
et
ISO-8859-1
Finnish
fi
ISO-8859-1
French
fr
ISO-8859-1
German
de
ISO-8859-1
Greek
el
ISO-8859-7
Hebrew
he
ISO-8859-8
Hungarian
hu
ISO-8859-2
Icelandic
is
ISO-8859-1
Italian
it
ISO-8859-1
Japanese
ja
Shift_JIS
Korean
ko
KSC_5601
Latvian (Lettish)
lv
ISO-8859-2
Lithuanian
lt
ISO-8859-2
Macedonian
mk
ISO-8859-5
Norwegian
no
ISO-8859-1
Polish
pl
ISO-8859-2
Portuguese
pt
ISO-8859-1
Romanian
ro
ISO-8859-2
Russian
ru
ISO-8859-5
Serbian
sr
ISO-8859-5
Serbo-Croatian
sh
ISO-8859-5
Slovak
sk
ISO-8859-2
Slovenian
sl
ISO-8859-2
Spanish
es
ISO-8859-1
Swedish
sv
ISO-8859-1
Turkish
tr
ISO-8859-9
Ukranian
uk
ISO-8859-5




End-Entity Forms and Templates
This section describes the end-entity interface and its default forms.

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 24.1 shows the end-entity interface of a Registration Manager.

Figure 24.1 End-entity services interface

Locating End-Entity Forms and Templates

You can find the HTML forms and the corresponding output templates for the end-entity interface at this location:

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

Forms for Certificate Enrollment

Table 24.2 lists the file names of forms that appear as menu options in the Enrollment tab of the end-entity interface. The forms are available on Certificate Manager instances and Registration Manager instances, The only exception is that the Certificate Manager enrollment form is available only on Certificate Manager instances.

Table 24.2 Forms for end-entity enrollment

Menu Link and Filename">Form Type: Menu Link and Filename
What form is used for...
User Enrollment (lists menu options for end-user enrollment)
Manual
(ManUserEnroll.html)

End users can use the User Enrollment forms to request SSL client and S/MIME certificates. Except for Manual, these links only appear when an appropriate authentication manager has been configured on the CMS server.
Directory Based
(DirUserEnroll.html)
Enroll using directory user ID and password.
Directory and PIN Based
(DirPinUserEnroll.html)
Enroll using directory user ID, password, and one time PIN.
NIS Server
(NISUserEnroll.html)
Enroll using authentication against a NIS server.
Portal
(PortalEnrollment.html)
Enroll using any unique user ID and a password.
Certificate
(CertBasedDualEnroll.html)
Enroll for dual key certificates using a pre-issued certificate (on a hardware token) for authentication.
Certificate
(CertBasedSingleEnroll.html)
Enroll for a single certificate using a pre-issued certificate (on a hardware token) for authentication. (This form is not used in the default interface.)
Certificate
(CertBasedEncryptionEnroll.html)
Enroll for an encryption certificate only using a pre-issued certificate (on a hardware token) for authentication. (Thisform is not used in the default interface.)

Server Enrollment (lists menu options for server enrollment)
SSL Server
(ManServerEnroll.html)
Server administrators can use this form to request SSL server certificates for servers.
Directory Based Server
(DirServerEnroll.html)
Server administrators can use this form to request SSL server certificates for servers.
OCSP Responder
(OCSPResponder.html)
Server administrators can use this form to request signing certificates for OCSP Responder servers.

Registration Manager Enrollment (lists menu options for Registration Manager enrollment)
Registration Manager
(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".

Certificate Manager Enrollment (lists menu options for Certificate Manager enrollment)
Certificate Manager
(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".

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

Object Signing (PKCS10) (ObjSignPKCS10Enroll.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 24.3 lists the forms that correspond to the menu options in the Renewal tab of the end-entity interface on Certificate Manager instances and Registration Manager instances.

Table 24.3 Forms for certificate renewal

Menu Link and Filename">Menu Link and Filename
What form is used for...
Server Certificate
(ServerRenewal.html)
Server administrators can use this form to renew server certificates.
User Certificate
(UserRenewal.html)

End users can use this form to renew their SSL client certificates and their S/MIME certificates if the S/MIME certificates were issued with the SSL client bit set.

Forms for Certificate Revocation

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

Table 24.4 Forms for certificate revocation

Menu Link and Filename">Menu Link and Filename
What form is used for...
Certificate (challenge phrase-based)
(ChallengeRevoke1.html)

End users can use this form to revoke their SSL client certificates using a password created during enrollment.
Server Revocation
(ServerRevocation.html)
Server administrators can use this form to revoke server certificates.
User Revocation (UserRevocation.html)
End users can use this form to revoke their SSL client certificates using SSL client authentication.

Forms for Certificate Retrieval

Table 24.5 lists the forms that correspond to the menu options in the Retrieval tab of the end-entity interface on Certificate Manager instances. Only the Import CA Certificate Chain interface is also available on Registration Manager instances.

Table 24.5 Forms provided for certificate retrieval

Menu Link and Filename">Menu Link and Filename
What form is used for...
List Certificates
(queryBySerial.html)
End users and administrators can use this form to list certificates based on their serial numbers.
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:
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
Import Certificate Revocation List
(DisplayCRL.html)
End users and administrators can use this form to:

Forms for Key Recovery

Table 24.6 lists the form that corresponds to the menu option in the Recovery tab of the end-entity interface. This form is available on a Certificate Manager instance or a Registration Manager instance that is configured as a trusted manager for a Data Recovery Manager instance.

Table 24.6 Form for encryption private key recovery

Menu Link and Filename">Menu Link and Filename
What form is used for...
Key Recovery
(KeyRecovery.html)
End users can use this form to retrieve their encryption private keys from the Data Recovery Manager.

Other Forms

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

Table 24.7 Files and forms used by other forms

Form filename
What form is used for...
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 other forms.
xenroll.dll
This file enables the end-user enrollment forms to work with Microsoft Internet Explorer.

Output Templates for End-Entity Interfaces

Table 24.8 lists the default templates that are used by the end-enetity interfaces to return data to the requestor.

Table 24.8 Response templates used by the end-entity 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 error messages to the user.
GenPending.template
Used to inform a user requesting a certificate that the request has been queued for agent approval.
GenRejected.template

Used to inform a user requesting a certificate that the request has been rejected by the CMS server.
GenSuccess.template

Used to inform a user requesting a certificate that the request has been approved by the CMS server.
GenSvcPending.template

Used to inform a user requesting a certificate that the request has been queued for agent approval.
GenUnauthorized.template

Used to inform users when thay perform unauthorized operations.
GenUnexpectedError.template

Used to inform the user that the CMS server encountered an unexpected error while processing the request.
ImportCert.template

Used to display the CA certificate when users import the CA certificate.
queryCert.template

Used to display the list of certificates when users search for certificates.
RenewalSuccess.template
Used to inform a user requesting a certificate renewal that the request has been successfully renewed.
RevocationSuccess.template
Used to inform a user requesting a certificate revocation that the certificate has been revoked.


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 24.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 24.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, as specified during installation.

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

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


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 following table describes the format an purpose of all the data included in the base <CMS_TEMPLATE> JavaScript:

Table 24.9 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.


End-entity Interface Reference
This section provides a detailed reference of all the service interfaces available on an end-entity port. For each interface, there is

The following table lists the end-entity interfaces and their functions:

Table 24.10 End-Entity Interfaces

Interface
URI
Purpose
Certificate Enrollment Protocol Interface
/pkiclient.exe
Process Simple Certificate Enrollment Protocol (SCEP) certificate requests from routers and other VPN clients.
Challenge Revocation Interface
/challenge_revocation1
Revoke a certificate using a challenge phrase set during enrollment.
Display Certificate By Serial Number Interface
/displayBySerial
Retrieve a certificate with a given serial number in human-readable form (use Get Certificate By Serial Number to get a binary form).
Display Certificate From Request Interface
/displayCertFromRequest
Used on a Registration Manager to display the certificate issued for a given request identifier.
Enrollment Interface
/enrollment
Process manual or automated certificate requests.
Get CA Chain Interface
/getCAChain
Retrieve the certificate authority's certificate or certificate chain (if the CA is not self-signed).
Get Certificate By Serial Number Interface
/getBySerial
Get a certificate with a given serial number in a binary format (for example, PKCS #7 or a CMMF response).
Get Certificate From Request Interface
/getCertFromRequest
Use the id assigned to a pending request to retrieve the certificate once it has been issued.
Get CRL Interface
/getCRL
Retrieve the Certificate Revocation List.
List Certificates Interface
/listCerts
List certificates based on flexible query criteria.
Renewal Interface
/renewal
Process requests for renewing a certificate presented to the interface using SSL client authentication.
Revocation Interface
/revocation
Process requests for manual revocation or for revocation of a certificate presented to the interface using SSL client authentication.

Certificate Enrollment Protocol Interface

Description

URI: /cgi-bin/pkiclient.exe

Available on: Certificate Manager and Registration Manager

Function: Handles Certificate Enrollment Protocol (CEP) requests from devices such as Virtual Private Network (VPN) routers.

VPN routers use CEP to enroll in and get information about their PKI. The Certificate Enrollment Protocol interface uses CEP to issue new certificates, distribute Certificate Revocation List (CRL) data, and distribute the CA certificate.

Default Forms

There are no forms that use the Certificate Enrollment Protocol. The interface is provided so that VPN clients, such as routers, can use CEP to interact with the PKI.

Request Parameters

You will not generally develop your own request forms or response templates for use with CEP. The Certificate Enrollment Protocol interface complies with the CEP protocol developed by Cisco, so if your application or device uses this protocol it will be able to use the Certificate Enrollment Protocol Interface.

To use the interface with a Cisco router, for example, you configure the router to point to the end-entity gateway port using the router's enrollment url command. You can then use crypto ca enroll to request a certificate:

> crypto ca identity Example

> enrollment url https://example:443/

> crypto ca enroll Example

The router uses the CEP protocol and expects to find the /cgi-bin/pkiclient.exe interface at the URL named by the enrollment url command. The details of interacting with the interface are handled by the protocol itself.

Challenge Revocation Interface

Description

URI: /challenge_revocation1

Available on: Certificate Manager and Registration Manager

Function: Allows an entity to revoke a certificate using a challenge password set during enrollment.

The Challenge Revocation interface is useful if an entity must revoke a certificate that is not available or not valid for SSL client authentication. (The Revocation Interface can be used to present a certificate using SSL client authentication for revocation.) To use this interface, the challenge password for revocation must be set during enrollment (see the challengePassword request parameter in Enrollment Interface).

Default Forms

The ChallengeRevoke1.html form is the only default form that uses the Challenge Revocation interface. It allows an end user to enter either the certificate's serial number or subject name and the challenge password to revoke the certificate.

Request Parameters

The following table lists the parameters accepted by the Challenge Revocation interface.

Table 24.11 Parameters Accepted by the Challenge Revocation Interface

Parameter
Format and Description
certSerialToRevoke
number (decimal or hexadecimal)
The serial number of the certificate to revoke. Either this parameter or subjectName are required.
challengePhrase
string
The challenge phrase, set during certificate enrollment, that allows the certificate to be revoked.
reasonCode
0-8
The code for the reason why the certificate is being revoked. This code is added to the Certificate Revocation List (CRL) entry for the revoked certificate. Valid reasonCode values are:
subjectName
Distinguished Name (DN) string. See RFC 2253.
The DN appearing in the certificate subject field. Either subjectName or certSerialToRevoke must be specified. The subject name should only be used when the subject DN is guaranteed to uniquely identify the certificate.
Example DN: CN=Alice Apple, UID=alice, OU=People, O=Example, C=US
templateName
string
Filename relative to the template directory (web/ee, web/agent/ca, web/agent/kra, or web/agent/ra) of a file to use as the response template. This template will be used for any response, overriding default template settings.
templateType
RevocationConfirmation
This parameter specifies which response template to use. At this time, the only valid value is "Revocation Confirmation." This value causes the revocationResult.template file to be used.

Response

The response from the Challenge Revocation interface will be identical to a response from the Revocation interface. See the Response section in Revocation Interface for details on what JavaScript variables are returned in the response template.

Display Certificate By Serial Number Interface

Description

URI: /displayBySerial

Available on: Certificate Manager

Function: Displays a single certificate in human-readable form.

The Display Certificate By Serial Number interface is typically used within a form that lists certificates to display detailed information about a selected certificate. The response is an HTML page built from a template (not just raw certificate data), so this interface should not be used to retrieve certificates for processing (such as importing into a browser); use the Get Certificate By Serial Number Interface (/getBySerial) instead.

Default Forms

The Display Certificate By Serial Number interface is used in the queryCert.template file. Each certificate in the list of certificates satisfying the query has a button the user can press to see the certificate in detail. This button submits data to the Display Certificate By Serial Number interface.

Request Parameters

The following table lists the parameters accepted by the Display Certificate By Serial Number interface.

Table 24.12 Parameters Accepted by the Display Certificate By Serial Number Interface

Parameter
Format and Description
op
displayBySerial
Specifies the operation to perform. The only valid value is displayBySerial.
serialNumber
number
The serial number of the certificate to display.
templateName
string
Filename relative to the template directory (web/ee, web/agent/ca, web/agent/kra, or web/agent/ra) of a file to use as the response template. This template will be used for any response, overriding default template settings.