Chapter 2   Introduction to End-Entity Services Interface


The services interfaces that come with iPlanet Certificate Management Server (CMS) make 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, 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 the default forms and templates used by the end-entity interface.

The chapter has the following sections:

• End-Entity Services Interface

• Accessing the End-Entity Services Interface

• End-Entity Forms and Templates

End-Entity Services Interface

---

Certificate Management System provides HTML forms for the various entities—people, routers, servers, and others—that use certificates to identify themselves and that need to be able to request certificate issuance and management operations. These forms, collectively called the End-Entity Services interface, use different protocols and life-cycle management procedures for different kinds of end entities. For example, the Certificate Manager provides separate certificate enrollment forms for clients such as Netscape Navigator 3.x, versions of Netscape Communicator later than 4.5, and Microsoft Internet Explorer. The reason for this is that end entities running Navigator 3.x and Communicator versions earlier than 4.5 present an enrollment form based on the use of the HTML tag KEYGEN to generate keys; end entities running Internet Explorer present a form based on PKCS #10, the RSA standard for certificate request syntax.

Figure 2-1 shows the end-entity services interface hosted by a Certificate Manager.

Figure 2-1    End-entity services interface

For a summary of the various end entities, protocols, cryptographic algorithms, and key pairs (single or dual) supported by Certificate Management System, see Table 2-1.

For a complete list of the end-entity forms—for enrollment, renewal, retrieval, revocation, and key recovery—that come with Certificate Management System, see End-Entity Forms and Templates.

How Client Type Determines the End-Entity Interface

Each type of end-entity form provided by Certificate Management System is served by a servlet. This servlet determines which version of the form to present based on information about the end entity (the type, version, language, and so on), information in the form itself, and other factors.

Each form also specifies both an authentication manager and an output template:

• An authentication manager is a configured instance of an authentication plug-in module. When Certificate Management System receives a request from an end entity, it uses the authentication manager specified by the request to determine how to authenticate the end entity. For more information, see Chapter 15, "Setting Up End-User Authentication" in CMS Installation and Setup Guide.

• The output template is an HTML page with embedded JavaScript used to return information from the end entity to the servlet. For more information, see Responses and Output Templates.

Based on all the information, a form's servlet sends the end entity the version of the form (including the embedded JavaScript code) appropriate for that end entity. For example, in the case of end entities that support the KEYGEN tag, the Certificate Manager or Registration Manager sends a form that uses KEYGEN to generate keys and formulate a certificate request. In the case of end entities that support the Certificate Management Message Format (CMMF) protocol, the Certificate Manager or Registration Manager sends a form that uses a JavaScript API to fully automate both key generation and certificate issuance.

Certificate Request Formats Specific to End Entities

Table 2-1 lists the forms provided by the Certificate Manager and Registration Manager for certificate issuance and life-cycle management operations, and indicates supported authentication mechanisms and request formats. You can customize any of the default forms and their corresponding servlets and output templates. For details, see Chapter 3 "End-Entity Interface Reference."

Table 2-1    Summary of end-entity forms, authentication methods and certificate request formats  

Form for end-entity operation	Authentication method	Supported certificate request formats
Certificate enrollment
Client (end user) certificates	Manual, LDAP directory based, and NIS server based	KEYGEN for Navigator/Communicator PKCS #10 for Internet Explorer Certificate Request Message Format (CRMF) for future versions of Communicator
Server certificates	Manual	PKCS #10
Cisco routers	Manual or automated	Certificate Enrollment protocol (CEP)
Certificate renewal
Client (end user) certificates	SSL client authentication	KEYGEN for Navigator/Communicator PKCS #10 for Internet Explorer CRMF for future versions of Communicator
Server certificates	Manual	PKCS #10
Cisco routers	Manual	CEP
Certificate revocation
Client (end user) certificates	SSL client authentication and challenge-password based	KEYGEN for Navigator/Communicator PKCS #10 for IE CRMF for future versions of Communicator
Server certificates	Manual	PKCS #10
Cisco routers	Manual	CEP
Encryption private key storage and recovery
Client (end user) certificates	Not applicable	Not supported for clients that can't generate dual key pairs CRMF for future versions of Communicator

Accessing the End-Entity Services Interface

---

By default, access to the end-entity services interface of a Certificate Manager or Registration Manager is open to all users. To access the Agent Services interface for a particular subsystem:

1. Open a web browser window.

2. Go to the page where the End-Entity Services interface for the Certificate Manager or Registration Manager is installed.

   The default URL for this page is:

   http://<hostname>:<ee_port> or https://<host_name>:<ee_ssl_port>

   <hostname> is in the form <machine_name>.<your_domain>.<domain>.

   The appropriate interface appears. (If you have disabled the unsecure end-entity port, you won't be able to access the interface on that port.)

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 2-1 shows the end-entity interface of a Certificate Manager.

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 2-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 2-2    Forms for end-entity enrollment  

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.
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.
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 2-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 2-3    Forms for certificate renewal  

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 2-4 lists the forms that correspond to the menu options in the Revocation tab of the end-entity services interface.

Table 2-4    Forms for certificate revocation  

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 2-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 2-5    Forms provided for certificate retrieval  

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: Serial number of the certificate Subject name of the certificate Revocation status of the certificate Issuing Information—when the certificate was issued Validity period of the certificate Type of certificate
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 the CA certificate chain into their browsers Download the CA certificate chain in binary form View the CA certificate chain for importing into a server Display certificates in the CA certificate chain for importing individually into a server
Import Certificate Revocation List (DisplayCRL.html)	End users and administrators can use this form to: Manually check the revocation status of a particular certificate (if they are not sure whether they have the latest version of the CRL) Import the latest CRL to Netscape Navigator Download the latest CRL in binary form View the CRL header information

Forms for Key Recovery

Table 2-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 2-6    Form for encryption private key recovery  

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 2-6 lists common forms that are used by the operation-specific forms in the end-entity interface.

Table 2-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 2-8 lists the default templates that are used by the end-enetity interfaces to return data to the requestor.

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