Chapter 1   Agent Services


This chapter describes the role of the privileged users called agents in managing iPlanet Certificate Management System (CMS). It also introduces the tools that agents use to administer service requests.

The chapter has the following sections:

• Overview of Certificate Management System

• Agent Tasks

• Forms for Performing Agent Operations

• Accessing Agent Services

Overview of Certificate Management System

---

Certificate Management System is a highly configurable set of software components and tools for creating, deploying, and managing certificates. The standards and services that facilitate the use of public-key cryptography and X.509 version 3 certificates in a networked environment are collectively called the public key infrastructure (PKI) for that environment. In any PKI, a certificate authority (CA) is a trusted entity that issues, renews, and revokes certificates. An end entity is a person, router, server, or other entity that uses a certificate to identify itself.

To participate in a PKI, an end entity must enroll, or register, in the system. The end entity typically initiates enrollment by giving the CA some form of identification and a newly generated public key. The CA uses the information provided to authenticate, or confirm, the identity; it then issues the end entity a certificate that associates that identity with the public key, and signs the certificate with the CA's own private signing key.

End entities and CAs may be in different geographic or organizational areas or in completely different organizations. CAs may include third parties that provide services through the Internet as well as the root CAs and subordinate CAs for individual organizations. Policies and certificate content may vary from one organization to another. End-entity enrollment for some certificates may require physical verification, such as an interview or notarized documents, while enrollment for others may be fully automated.

To meet the widest possible range of configuration requirements, Certificate Management System permits the independent installation of four separate subsystems, or "managers," that typically play distinct roles:

• Certificate Manager—A Certificate Manager functions as a root or subordinate certificate authority. This subsystem issues, renews, and revokes certificates, generates certificate revocation lists (CRLs). It can publish certificates to a Lightweight Directory Access Protocol (LDAP) directory and files, and CRLs to an LDAP directory, a file, and an Online Certificate Status Protocol (OCSP) responder. The Certificate Manager can be configured to accept requests from end entities, Registration Managers, or both, and can process requests either manually (that is, with the aid of a human being) or automatically (based entirely on customizable policies and procedures). When set up to work with a separate Registration Manager, the Certificate Manager processes requests and returns the signed certificates to the Registration Manager for distribution to the end entities. (For an overview of the role of certificate authorities and related concepts of public-key cryptography, see Appendix D of Managing Servers with Netscape Console.)

  Note that the publishing tasks can be performed by the Certificate Manager only. The Certificate Manager also has a built-in OCSP service, enabling OCSP-compliant clients to directly query the Certificate Manager about the revocation status of a certificate that it has issued. In certain PKI deployments, it might be convenient to use the Certificate Manager's built-in OCSP service, instead of a Online Certificate Status Manager.

• Registration Manager—A Registration Manager is an optional component in the PKI and can be used to separate the registration process from the certificate-signing process. The Registration Manager performs a subset of the end-entity tasks performed by the Certificate Manager, such as enrollment or renewal, on behalf of the Certificate Manager. A Registration Manager is typically installed on a different machine from the Certificate Manager that it serves. After the Registration Manager approves requests, it forwards them to this Certificate Manager, which trusts the Registration Manager to provide reliable authentication services and therefore trusts any signed requests it submits. The Certificate Manager processes the requests and issues the certificates. The Registration Manager then distributes the certificates to the end entities.

• Data Recovery Manager—A Data Recovery Manager oversees the long-term archival and recovery of private encryption keys for end entities. A Certificate Manager or Registration Manager can be configured to archive end entities' private encryption keys with a Data Recovery Manager as part of the process of issuing new certificates. The Data Recovery Manager is useful only if end entities are encrypting data (using applications such as S/MIME email) that the organization may need to recover someday. It can be used only with client software that supports dual key pairs—that is, two separate key pairs, one for encryption and one for digital signatures. This service is available in newer clients only; for example, Communicator versions 4.7x (with Netscape Personal Security Manager installed) and Netscape 6 support generation of dual key pairs. The Data Recovery Manager archives encryption keys. It does not archive signing keys, since such archival would undermine nonrepudiation properties of dual-key certificates.

• Online Certificate Status Manager—A Online Certificate Status Manager performs the task of an online certificate validation authority, by enabling OCSP-compliant clients to do real-time verification of certificates. The Online Certificate Status Manager can receive CRLs from multiple Certificate Managers and clients can query the Online Certificate Status Manager for the revocation status of certificates issued by all these Certificate Managers. For example, in a PKI comprising multiple CAs (a root CA and many subordinate CAs) each CA can be configured to publish its CRL to the Online Certificate Status Manager. This way, all clients in the PKI deployment can verify the revocation status of a certificate by querying the Online Certificate Status Manager.

  Note that an online certificate-validation authority is often referred to as OCSP responder.

Since CAs can delegate some responsibilities to subordinate CAs, a Certificate Manager might delegate responsibilities to one or more levels of subordinate Certificate Managers, and Registration Managers might delegate responsibilities to subordinate Registration Managers. Therefore many complex variations are possible.

Three kinds of entities can access CMS subsystems: administrators, agents, and end entities. Administrators are responsible for the initial setup and ongoing maintenance of the subsystems. Administrators can designate users with special privileges, called agents, for each subsystem. Agents manage day-to-day interactions with end entities and other aspects of the PKI. This guide describes the tasks that agents can perform. End entities access Registration Manager or Certificate Manager subsystems to enroll in a PKI and to take part in other life-cycle management operations, such as renewal or revocation.

Figure 1-1 shows the ports used by administrators, agents, and end entities. All agent and administrator interactions with CMS subsystems occur over HTTPS. End-entity interactions can take place over HTTP or HTTPS.

Figure 1-1    Certificate Management System and its users

Agent Tasks

---

The designated agents for each subsystem are responsible for the everyday management of end-entity requests and other aspects of the PKI:

• Certificate Manager agents manage certificate requests received by the Certificate Manager subsystem, maintain and revoke certificates as necessary, and maintain global information about certificates.

• Registration Manager agents manage the certificate requests received by the Registration Manager subsystem.

• Data Recovery Manager agents initiate the recovery of lost keys, and can obtain information about key service requests and archived keys.

• Online Certificate Status Manager agents can perform tasks such as checking which CAs are currently configured to publish their CRLs to the Online Certificate Status Manager, identifying a Certificate Manager to the Online Certificate Status Manager, adding CRLs directly to the Online Certificate Status Manager, and viewing the status of OCSP service requests submitted by OCSP-compliant clients.

To perform the privileged operations of an agent, you use the CMS Agent Services pages. To access these pages, you must have a personal SSL client certificate, and the CMS administrator must have identified you as a privileged user in the user database. For more information on how to get set up as a privileged user, see CMS Installation and Setup Guide.

Certificate Manager Agent Services

The default entry page to the Certificate Manager agent services is shown in Figure 1-2. To access these pages, you must be a designated Certificate Manager agent and your client software must have a valid certificate identifying you as such.

Figure 1-2    Certificate Manager Agent Services page

As a Certificate Manager agent, you can perform the following tasks:

• Handle certificate requests.

  You can list the certificate service requests received by the Certificate Manager subsystem, assign requests to yourself, reject or cancel requests, and approve requests for certificate enrollment. See , "Handling Certificate Requests."

• Clone requests.

  You can clone any request, whether it's still pending, canceled, rejected, or completed. This can be useful in a variety of situations. For example, if a user receives a certificate that doesn't work because it has been incorrectly formulated, you can locate the completed request, clone it, and correct it without requiring the user to enroll a second time. Cloning a request gives it a new request ID number and puts it into the list of pending requests, but does not change the status of the original request.

• Find certificates.

  You can search for individual certificates, or search for and list certificates by various criteria, then display the details of certificates you have found. See Chapter 3 "Finding and Revoking Certificates"

• Revoke certificates.

  If a user's key has been compromised, you need to revoke the user's certificate to ensure that the key is not misused. You may also need to revoke the certificates of users who have left the organization. You can use Certificate Manager Agent Services to find and revoke a specific certificate or a set of certificates. Users can also revoke their own certificates. See "Revoking Certificates"in Chapter 3.

• Update the CRL.

  The Certificate Manager maintains a public list of certificates that have been revoked, called the certificate revocation list (CRL). The list is usually maintained automatically, but you may sometimes need to use the Certificate Manager Agent Services page to update the list manually. See "Updating the CRL" in Chapter 3.

• Publish certificates to a directory.

  You can set up Certificate Management System to publish certificates and lists of revoked certificates in an LDAP directory. Certificate information is usually published automatically, but you may sometimes need to use the Certificate Manager Agent Services page to update the directory manually. See Chapter 4 "Publishing to a Directory"

Registration Manager Agent Services

The default entry page to the Registration Manager agent services is shown in Figure 1-3. To access these pages, you must be a designated Registration Manager agent and your client software must have a valid certificate identifying you as such.

Figure 1-3    Registration Manager Agent Services page

As a Registration Manager agent, you can handle certificate requests. You can list the certificate service requests received by the Registration Manager subsystem, assign requests to yourself, reject or cancel requests, clone requests, and approve enrollment requests to be passed on to the Certificate Manager for issuance. See Chapter 2 "Handling Certificate Requests"

Data Recovery Manager Agent Services

The default entry page to the Data Recovery Manager agent services is shown in Figure 1-4. To access these pages, you must be a designated Data Recovery Manager agent and your client software must have a valid certificate identifying you as such.

Figure 1-4    Data Recovery Manager Agent Services page

As a Data Recovery Manager agent, you can perform the following tasks:

• List key recovery requests from end entities.

• List or search for archived keys.

• Initiate the recovery of private data-encryption keys.

Key recovery requires the authorization of one or more recovery agents. The administrator for the Data Recovery Manager designates recovery agents. Typically, several recovery agents own portions of the storage key for the Data Recovery Manager. The approval of m of a total of n agents is required to authorize key recovery. The values of m and n for your installation of the Data Recovery Manager is determined by the administrator in charge of the subsystem.

For more information on these tasks, see Chapter 5 "Recovering Encrypted Data."

Online Certificate Status Manager Agent Services

The default entry page to the Online Certificate Status Manager agent services is shown in Figure 1-5. To access these pages, you must be a designated Online Certificate Status Manager agent and your client software must have a valid certificate identifying you as such.

Figure 1-5    Online Certificate Status Manager Agent Services page

As a Online Certificate Status Manager agent, you can perform the following tasks:

• Checking which CAs are currently configured to publish their CRLs to the Online Certificate Status Manager.

• Identifying a Certificate Manager to the Online Certificate Status Manager.

• Adding CRLs directly to the Online Certificate Status Manager.

• Checking the revocation status of a certificate by submitting it to the Online Certificate Status Manager.

For more information on these tasks, see Chapter 6 "Managing OCSP Service Related Tasks."

Forms for Performing Agent Operations

---

The agent services consist of a form-based HTML interface that is part of your Certificate Management System installation. The CMS administrator designates particular users as agents for each installed subsystem (Certificate Manager, Registration Manager, Data Recovery Manager, and ). Only a designated agent for a subsystem can use the Agent Services interface for that subsystem. In addition, you must have a personal client SSL certificate to access the Agent Services interface.

As a subsystem agent with the proper certificate, you use the Agent Services page to access the forms you need to perform the agent tasks. Table 1-1 describes each of these HTML forms.

Table 1-1    Forms used for agent operations  

Form name	Description
List Requests (Certificate Manager and Registration Manager)	Use this form to examine, select, and process requests for certificate services. Both Certificate Manager and Registration Manager agents can use this form. For instructions on using this form, see "Listing Certificate Requests" in Chapter 2.
List Certificates (Certificate Manager)	Use this form to list certificates within a range of serial numbers. You can limit the list to valid certificates. Only Certificate Manager agents can use this form. For instructions on using this form, see "Basic Certificate Listing" in Chapter 3.
Search for Certificates (Certificate Manager)	Use this form to search for and list certificates issued by Certificate Management System. Only Certificate Manager agents can use this form. This form allows you to search by subject name or by certificate type, the state of the certificate (expired, revoked, and so on), and the dates when the certificate was issued or revoked, expired, or became valid. For instructions on using this form, see "Advanced Certificate Search" in Chapter 3.
Revoke Certificates (Certificate Manager)	Use this form to search for and revoke certificates issued by Certificate Management System. Only Certificate Manager agents can use this form. For instructions on using this form, see "Revoking Certificates" in Chapter 3.
Update Revocation List (Certificate Manager)	Use this form to manually update the published list of revoked certificates. Only Certificate Manager agents can use this form. For instructions on using this form, see "Managing the Certificate Revocation List" in Chapter 3.
Update Directory Server (Certificate Manager)	Use this form to update the LDAP publishing directory with changes in certificate information (newly issued certificates, updated CRLs, and so on). Only Certificate Manager agents can use this form. For instructions on using this form, see "Updating the Directory with Changes" in Chapter 4.
List Requests (Data Recovery Manager)	Use this form to find and examine requests for key services. Only Data Recovery Manager agents can use this form. For instructions on using this form, see "Viewing Key Service Requests" in Chapter 5.
Search for Keys (Data Recovery Manager)	Use this form to find and list specific archived keys. Only Data Recovery Manager agents can use this form. For instructions on using this form, see "Finding Archived Keys" in Chapter 5.
Recover Keys (Data Recovery Manager)	Use this form to find and recover specific archived keys. Only Data Recovery Manager agents can use this form. You can select a key in the list returned by a search and initiate its recovery, which must be authorized by designated key recovery agents. For instructions on using this form, see "Recovering Keys" in Chapter 5.
Authorize Recovery (Data Recovery Manager)	Use this form to remotely authorize a key recovery request initiated by another Data Recovery Manager agent. Key recovery agents do not have to be Data Recovery Manager agents if key recovery is handled locally; however, only key recovery agents who are also Data Recovery Manager agents can access this form. For instructions on using this form, see "Recovering Keys" in Chapter 5.
List Certificate Authorities (Online Certificate Status Manager)	Use this form to list Certificate Managers that are currently configured to publish their CRLs to the Online Certificate Status Manager. For instructions, see "Listing CAs Identified by Online Certificate Status Manager" in Chapter 6.
Add Certificate Authority (Online Certificate Status Manager)	Use this form to identify a Certificate Manager to the Online Certificate Status Manager. For instructions, see "Identifying a CA to Online Certificate Status Manager" in Chapter 6.
Add Certificate Revocation List (Online Certificate Status Manager)	Use this form to add a CRL to the Online Certificate Status Manager's internal database. For instructions, see "Adding a CRL to Online Certificate Status Manager" in Chapter 6.
Check Certificate Status (Online Certificate Status Manager)	Use this form to check the status of OCSP service requests sent by OCSP-compliant clients. For instructions, see "Checking the Revocation Status of a Certificate" in Chapter 6.

Accessing Agent Services

---

Access to the agent services forms requires certificate-based authentication. Only users who authenticate with the correct certificate and who have been granted the proper access privilege can access and use the forms. The operation uses the SSL protocol; that is, you connect to the server using HTTPS (not HTTP) on the SSL agent port. For example, if Certificate Management System is installed on a host named cert.siroe.com and is running on port 443 (the default port for SSL connections), you invoke the Agent Services interface by using the following URL:

https://cert.siroe.com:443

The Agent Services pages are written in HTML and are intended to be customized. This document describes the default pages. If your administrator has customized these pages, yours may differ from those described here. Check with the CMS administrator for information on your local installation.

Administrator/Agent Certificate Enrollment

Immediately after installing any CMS instance, the administrator must enroll for the initial administrator/agent certificate. This is the first user certificate that Certificate Management System issues.

The initial user is both an administrator and an agent. This person can create additional agents with the appropriate user privileges and issue them certificates. Since there is no agent yet to approve the request, a special enrollment form allows you to get this first certificate automatically.

After you submit this initial Administrator/Agent Certificate Enrollment form, it is automatically disabled, so that no one else can acquire a certificate without agent approval or some form of automated authentication. The system automatically adds the initial user to the list of agents.

To enroll for the first agent certificate, you should be working at the computer you intend to use as the agent, so that the new certificate will be installed in the browser you will be using to access the Agent Services pages. Follow these steps:

1. Open a web browser window.

2. Go to the URL for the SSL agent port.

   By default, this is a URL of the following form:

   https://<hostname>:<agent_port>

   <hostname> is the fully qualified domain name of the machine on which Certificate Management System is installed; for example, cert.siroe.com.

   <agent_port> is the TCP port specified during installation for agent communications over SSL; for example, 8100.

   The first time you access this port, the system opens the Administrator/Agent Certificate Enrollment form.

   Because you have accessed an SSL port, Certificate Management System presents its server SSL certificate to your browser for authentication. This is the server SSL certificate that you created during installation. Because you just created it, it is not on your browser's list of trusted certificates. Before you see the Administrator/Agent Certificate Enrollment form, a series of dialog boxes appear that let you add the CMS server certificate to your list of trusted certificates.

3. Complete the dialog boxes as instructed (the exact procedure depends on the browser you are using).

4. In the Administrator/Agent Certificate Enrollment form, enroll for a client SSL certificate as the system's first privileged user by entering the following information:

   Authentication Information section:

   User ID. The ID you entered for the CMS administrator during installation.

   Password. The password you specified for the CMS administrator during installation.

   Subject Name section (The subject name is the distinguished name (DN) that identifies the certified owner of the certificate.)

   Full name. Name of administrator/agent.

   Login name. User ID of administrator/agent.

   Email address. Email address of administrator/agent.

   Organization unit. Name of the organization unit to which the administrator/agent belongs.

   Organization. Name of the company or organization the administrator/agent works for.

   Country. Two-letter code for the administrator/agent's country.

   User's Key Length Information section:

   Key Length. The length of the private key that will be generated by your browser. This key corresponds to the public key that is part of the administrator/agent certificate.

   Note that the validity period of this initial agent certificate is hard-coded as one year.

5. Click Submit.

6. Follow the instructions your browser presents as it generates a key pair.

7. If authentication is successful, the new certificate will be imported into your browser, and you will be given an opportunity to make a backup copy.

Now you have a client authentication certificate in the name you specified. This special user, who was named as the initial administrator for Certificate Management System during installation, has been automatically designated as the first agent. This certificate allows you to access the Agent Services pages. As an agent, you can approve enrollment requests and start issuing new certificates. To access the CMS windows in Netscape Console, you use the user ID that you specified for the certificate and the corresponding password—both of which must correspond to the values you specified for the CMS administrator during installation.

Note that after you submit the initial Administrative Enrollment form, it is no longer available from the agent port. If something goes wrong and you are unable to obtain the administrator/agent certificate, you must reset a parameter in the configuration file to make the initial administrative enrollment form available again. Follow these steps:

1. In the left frame of Netscape Console, open the CMS instance for which you want to display the Administrator/Agent Certificate Enrollment form.

   The server requests the password for the CMS administrator.

2. Click the icon labeled "Stop the Server."

3. Go to this directory: <server_root>/cert-<instance_ID>/config

4. Open the CMS.cfg file in a text editor, and find the following line: agentGateway.enableAdminEnroll=false

5. Change false to true, and save the file.

6. Start the server from the CMS window where you stopped it. (Alternatively, right-click on the name of the instance in the left frame and choose Start Server.) At this point, the server asks you for the single signon password you specified during installation.

7. The next time you access the SSL agent port, the Administrator/Agent Certificate Enrollment form will be available again.

Agent Services Entry Page

To access the Agent Services interface in a default installation:

1. Open a browser.

2. Go to the URL for the SSL agent port.

   This is the same URL you used to access the initial Administrator/Agent Certificate Enrollment form.

3. In the Agent Services entry page, click the subsystem whose agent services you require.

   
   
   

The choices depend on which subsystems have been installed in the particular Certificate Management System instance. If you present a valid certificate and have been designated as an agent for a subsystem, you can access and use the Agent Services pages for that subsystem by clicking the link on this page.

If you do not yet have your certificate, click Services Summary to enroll for one. For more information, see "Services Summary Page" (the next section).

Services Summary Page

If you want to access another gateway without looking up the port number, click Services Summary on the Agent Services entry page. The Services Summary page gives you access to each of the configured gateways: the HTTPS end-entity gateway, the HTTP end-entity gateway (if it has been enabled), and the Agent Services entry page.

Figure 1-6    Services Summary page

If you do not yet have a certificate that allows you access to the Agent Services pages, go to one of the end-entity gateways and enroll for your certificate.