Chapter 1

Agent Services

---

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

This chapter contains the following sections:

• Overview of Certificate System
• Agent Tasks
• Forms for Performing Agent Operations
• Accessing Agent Services

Overview of Certificate System

Certificate 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 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 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 Red Hat 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), Netscape 6.2, and Netscape 7.x all 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 each Certificate Manager can interact with multiple Registration Managers. Therefore many complex variations are possible.

Three kinds of entities can access CS 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 (people, SSL-enabled servers, routers, and so on) 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 CS subsystems occur over HTTPS. End-entity interactions can take place over HTTP or HTTPS.

Figure 1-1 Certificate 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 CS Agent Services pages. To access these pages, you must have a personal SSL client certificate, and the CS 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 Administrator's 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 Chapter 3, "Handling Certificate Requests."

• 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 4, "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" on page 62.

• 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" on page 67.

• Publish certificates to a directory.

You can set up Certificate 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 5, "Publishing to a Directory."

• Manage Certificate Profiles.

The Agent user can enable and disable Certificate Profiles. The Agent must temporarily disable a profile so the administrator can use the Admin interface to make detailed changes to the profile itself. Once the changes have been made, the agent can re-enable the profile for regular use.

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. The agent can also update and validate requests making use of Certificate Profiles. See Chapter 3, "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 6, "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 7, "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 System installation. The CS administrator designates particular users as agents for each installed subsystem (Certificate Manager, Registration Manager, Data Recovery Manager, and Online Certificate Status Manager). 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" on page 39.
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" on page 53.
Search for Certificates (Certificate Manager)	Use this form to search for and list certificates issued by Certificate 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" on page 55.
Revoke Certificates (Certificate Manager)	Use this form to search for and revoke certificates issued by Certificate System. Only Certificate Manager agents can use this form. For instructions on using this form, see "Revoking Certificates" on page 62.
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" on page 66.
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" on page 70.
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" on page 80.
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" on page 73.
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" on page 77.
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" on page 77.
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" on page 85.
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" on page 86.
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" on page 88.
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" on page 90.
Agent-Initiated User Enrollment (RA)	Use this form to enable Directory based Agent-initiated User Enrollment. Once this feature is enabled agents can enroll users by using a simple enrollment form on the user's behalf.
Manage Certificate Profiles (CA,RA)	Use this form to Enable and Disable supported Certificate Profiles. Once a profile is disabled, the Administrator is free to make more detailed changes to the profile itself.
OCSP Service (CA)	Use this form to manage the operation of the CS internal OCSP service. This optional service can be enabled during the CS installation procedure.

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 System is installed on a host named CShost.example.com and is running on port 8100, you invoke the Agent Services interface by using the following URL:

https://CShost.example.com:8100
 

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 CS administrator for information on your local installation.

Administrator/Agent Certificate Enrollment

Immediately after installing any CS instance, the administrator must enroll for the initial administrator/agent certificate. This is the first user certificate that Certificate 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. To open the Administrator/Agent Certificate Enrollment form, type the following in a browser's URL field:

https://<hostname>:<admin_port>/ca/adminEnroll.html

where <hostname> is the fully qualified domain name of the machine on which Certificate System is installed (for example, CShost.example.com) and <admin_port> is the TCP port specified during installation for communications over SSL with the administration console.

Because you have accessed an SSL port, Certificate System presents its server SSL certificate to your browser for authentication. This is the SSL server 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 CS 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 CS administrator during installation.

Password. The password you specified for the CS 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.

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 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 CS windows in Red Hat 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 CS 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. Stop Certificate System.

You can stop the server from either the command-line or from Red Hat Console. To do this from Red Hat Console, in the left frame of Red Hat Console, open the CS instance for which you want to display the Administrator/Agent Certificate Enrollment form. The server requests the password for the CS administrator. Enter the password. When the CS Console opens, go to the Tasks tab and click the icon labeled "Stop the Server."

2. Go to this directory: <server_root>/cert-<instance_ID>/config
3. Open the CS.cfg file in a text editor, and find the following line: CSGateway.enableAdminEnroll=false
4. Change false to true, and save the file.
5. Start the server from the CS 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 sign-on password you specified during installation.
6. The next time you access the SSL agent port (via the browser), the Administrator/Agent Certificate Enrollment form will be available again.

Agent Services Entry Page

Once you have obtained the initial/first agent certificate, you can view the Agent Services interface by going to the agent port.

1. Open a browser.
2. Go to the URL for the SSL agent port.

The URL is in this format: https://<hostname>:<agent_port>

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

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.