Red Hat CERTIFICATE SYSTEM 7.3 - ADMINISTRATION User manual

Red Hat Certificate System
7.3
Agents Guide
Publication date: May 2007, updated August 4, 2009

Red Hat Certificate System 7.3 Agents Guide
Copyright ©2009 Red Hat, Inc.
Copyright ©2009 Red Hat, Inc.. This material may only be distributed subject to the terms and condi-
tions set forth in the Open Publication License, V1.0 or later (the latest version of the OPL is presently
available at http://www.opencontent.org/openpub/).
Red Hat and the Red Hat "Shadow Man" logo are registered trademarks of Red Hat, Inc. in the United
States and other countries.
All other trademarks referenced herein are the property of their respective owners.
1801 Varsity Drive
Raleigh, NC 27606-2072 USA
Phone: [phone]
Phone: [phone]
Fax: [phone]
PO Box 13588 Research Triangle Park, NC 27709 USA
Agents Guide

1. About This Guide 1
1.1. Required Concepts ................................................................................................1
1.2. What Is in This Guide ............................................................................................1
1.3. Examples and Formatting ......................................................................................2
1.3.1. File Locations for Examples and Commands ........................................................2
1.3.2. Using Mozilla LDAP Tools ...................................................................................2
1.3.3. Default Port Numbers .........................................................................................3
1.3.4. Guide Formatting ................................................................................................3
1.4. Additional Reading ................................................................................................4
1.5. Giving Feedback ...................................................................................................5
1.6. Document History ..................................................................................................5
2. Agent Services 7
2.1. Overview of Certificate System ...............................................................................7
2.1.1. Certificate System Sub-systems ..........................................................................7
2.1.2. Certificate System Users .....................................................................................9
2.2. Agent Tasks ........................................................................................................10
2.2.1. Certificate Manager Agent Services ...................................................................12
2.2.2. Data Recovery Manager Agent Services ............................................................13
2.2.3. Online Certificate Status Manager Agent Services ..............................................14
2.2.4. Token Processing System Agent Services .........................................................15
2.3. Forms for Performing Agent Operations ................................................................17
2.4. Accessing Agent Services ....................................................................................20
3. CA: Working with Certificate Profiles 23
3.1. About Certificate Profiles .....................................................................................23
3.1.1. Categories of Certificate Profiles ........................................................................23
3.2. Profile Operations Performed by CA Agents ..........................................................23
3.3. List of Certificate Profiles .....................................................................................24
3.3.1. Example Profile ................................................................................................26
3.4. How Certificate Profiles Work ...............................................................................29
3.5. Enabling and Disabling Certificate Profiles ............................................................30
3.5.1. Getting Certificate Profile Information .................................................................30
3.5.2. End User Certificate Profile ...............................................................................30
3.5.3. Policy Information .............................................................................................30
3.5.4. Approving a Certificate Profile ...........................................................................31
3.5.5. Disapproving a Certificate Profile .......................................................................31
4. CA: Handling Certificate Requests 33
4.1. Managing Requests ............................................................................................33
4.2. Listing Certificate Requests ..................................................................................34
4.2.1. Selecting a Request .........................................................................................37
4.2.2. Searching Requests .........................................................................................38
4.3. Approving Requests ............................................................................................39
4.4. Sending an Issued Certificate to the Requester .....................................................41
5. CA: Finding and Revoking Certificates 45
5.1. Basic Certificate Listing .......................................................................................45
5.2. Advanced Certificate Search ................................................................................46
5.3. Examining Certificates .........................................................................................51
5.4. Revoking Certificates ...........................................................................................52
5.4.1. Searching for Certificates to Revoke ..................................................................53
5.4.2. Revoking One or More Certificates ....................................................................54
5.5. Managing the Certificate Revocation List ..............................................................57
5.5.1. Viewing or Examining CRLs ..............................................................................57
v

5.5.2. Updating the CRL .............................................................................................58
6. CA: Publishing to a Directory 61
6.1. Automatic Directory Updates ................................................................................61
6.2. Manual Directory Updates ....................................................................................61
7. DRM: Recovering Encrypted Data 65
7.1. List Requests ......................................................................................................65
7.2. Finding and Recovering Keys ...............................................................................66
7.2.1. Finding Archived Keys ......................................................................................67
7.2.2. Recovering Keys ..............................................................................................70
8. OCSP: Agent Services 75
8.1. Listing CAs Identified by the OCSP ......................................................................75
8.2. Identifying a CA to the OCSP ...............................................................................76
8.3. Adding a CRL to the OCSP ..................................................................................78
8.4. Checking the Revocation Status of a Certificate ....................................................79
9. TPS: Agent Services 81
9.1. Basic Operations for an Agent and Administrator ...................................................81
9.2. Adding Tokens ....................................................................................................82
9.3. Managing Tokens ................................................................................................82
9.3.1. Changing Token Status ....................................................................................85
9.3.2. Editing the Token .............................................................................................86
9.3.3. Listing Token Certificates ..................................................................................87
9.3.4. Conflicting Token Certificate Status Information ..................................................87
9.3.5. Showing Token Activities ..................................................................................88
9.4. Listing and Searching Certificates ........................................................................88
9.5. Searching Token Activities ...................................................................................88
9.6. Administrator Operations .....................................................................................89
9.6.1. Showing Token Activities ..................................................................................89
9.6.2. Editing the Token .............................................................................................89
9.6.3. Deleting the Token ...........................................................................................89
Index 91
Agents Guide
vi

About This Guide
This guide describes the agent services interfaces used by Red Hat Certificate System agents to ad-
minister subsystem certificates and keys and other management operations.
This guide is intended for Certificate System agents. Agents are privileged users designated by the
Certificate System administrator to manage requests from end entities for certificate-related services.
Each installed Certificate System subsystem; Certificate Manager (CM), Data Recovery Manager
(DRM), Online Certificate Status Manager, Token Key Service (TKS), and Token Processing System
(TPS), can have multiple agents.
1.1. Required Concepts
Before reading this guide, be familiar with the basic concepts of public-key cryptography and the Se-
cure Sockets Layer (SSL) protocol, including the following topics:
•Encryption and decryption
•Public keys, private keys, and symmetric keys
•Digital signatures
•The role of digital certificates in a public-key infrastructure (PKI)
•Certificate hierarchies
•SSL cipher suites
•The purpose of and major steps in the SSL handshake
1.2. What Is in This Guide
This guide describes an agent's responsibilities for the different Certificate System subsystems, and
explains basic usage and tasks.
•Chapter 2, Agent Services provides an overview of the product and identifies different kinds of
users, including agents. The chapter also summarizes the tasks of each subsystem agent, lists the
HTML forms used to perform agent tasks, and explains how to access the agent services pages and
forms.
•Chapter 3, CA: Working with Certificate Profiles provides an overview of the profiles feature and de-
tails how to enable and disable profiles.
•Chapter 4, CA: Handling Certificate Requests describes the general procedures for handling re-
Chapter 1.
1

quests and explains how to handle different aspects of certificate request management. A CM agent
is responsible for handling requests by end entities (end users, server administrators, or other Certi-
ficate System subsystems) for certificates using manual enrollment.
•Chapter 5, CA: Finding and Revoking Certificates explains how to use the agent services page to
find and examine a specific certificate issued by Certificate System, how to retrieve a list of certific-
ates that match specified criteria, how to revoke certificates, and how to manage the certificate re-
vocation list.
•Chapter 6, CA: Publishing to a Directory describes how a CM agent can update the LDAP directory
with the current status of certificates.
•Chapter 7, DRM: Recovering Encrypted Data describes how to process key recovery requests and
how to recover stored encrypted data when the encryption key has been lost. This service is only
available when a Data Recovery Manager (DRM) is installed.
•Chapter 8, OCSP: Agent Services describes how to handle tasks related to the Certificate System
OCSP responder, Online Certificate Status Manager. This service is only available when the OCSP
subsystem is installed.
•Chapter 9, TPS: Agent Services describes how to perform tasks related to the Token Processing
System and how to manage tokens and certificates through this subsystem. This service is only
available when the TPS subsystem is installed.
1.3. Examples and Formatting
1.3.1. File Locations for Examples and Commands
All of the examples for Red Hat Certificate System commands, file locations, and other usage are giv-
en for Red Hat Enterprise Linux 4 (32 bit) systems. Be certain to use the appropriate commands and
files for your platform.
To start the Red Hat Certificate System:
/etc/init.d/rhpki-ca start
Example 1.1. Example Command
All of the tools for Red Hat Certificate System are located in the /usr/bin directory. These tools can
be run from any location without specifying the tool location.
1.3.2. Using Mozilla LDAP Tools
Chapter 1. About This Guide
2

There is another important consideration with the LDAP utilities. The LDAP tools referenced in this
guide are Mozilla LDAP, installed with Red Hat Certificate System in the /usr/dir/mozldap direct-
ory on Red Hat Enterprise Linux.
However, Red Hat Enterprise Linux systems also include LDAP tools from OpenLDAP in the /
usr/bin directory. It is possible to use the OpenLDAP commands as shown in the examples, but you
must use the -x argument to disable SASL, which OpenLDAP tools use by default.
1.3.3. Default Port Numbers
After Errata RHSA-2009:0007, Certificate System 7.3 supports port separation. Port separation means
that the different subsystem services for administrators, agents, and end entities run on different, user-
defined ports.
The default subsystem instances, however, are configured to use a single secure port for all services.
Therefore, any example commands or files reference these default ports.
Susbsystem SSL Port Non-SSL Port
CA 9443 9080
RA 12889 12888
DRM 10443 10080
OCSP 11443 11080
TKS 13443 13080
TPS 7889 7888
Table 1.1. Default Subsystem Ports
1.3.4. Guide Formatting
Certain words are represented in different fonts, styles, and weights. Different character formatting is
used to indicate the function or purpose of the phrase being highlighted.
Formatting Style Purpose
Monospace font Monospace is used for commands, package names, files and
directory paths, and any text displayed in a prompt.
Monospace
with a
background
This type of formatting is used for anything entered or returned
in a command prompt.
Italicized text Any text which is italicized is a variable, such as in-
stance_name or hostname. Occasionally, this is also used to
emphasize a new term or other phrase.
Bolded text Most phrases which are in bold are application names, such as
Cygwin, or are fields or options in a user interface, such as a
User Name Here: field or Save button.
Default Port Numbers
3

Other formatting styles draw attention to important text.
NOTE
A note provides additional information that can help illustrate the behavior of the system
or provide more detail for a specific issue.
IMPORTANT
Important information is necessary, but possibly unexpected, such as a configuration
change that will not persist after a reboot.
WARNING
A warning indicates potential data loss, as may happen when tuning hardware for max-
imum performance.
1.4. Additional Reading
The Certificate System Administrator's Guide describes how to set up, configure, and administer the
Certificate System subsystems and how to configure backend certificate management functions, such
as publishing and logging. The Administrator's Guide also describes how to configure subsystems to
relate to one another to manage certificates and tokens and how to manage certificates and tokens;
this guide is targeted for Certificate System administrators.
The Certificate System Agent's Guide describes how agents — users responsible for processing certi-
ficate requests and managing other aspects of certificate management — can use the Certificate Sys-
tem subsystems web services pages to process certificate requests, key recovery, OCSP requests
and CRLs, and other functions.
The documentation for Certificate System includes the following guides:
•Certificate System Administrator's Guide explains all administrative functions for the Certificate Sys-
tem, such as adding users, creating and renewing certificates, managing smart cards, publishing
CRLs, and modifying subsystem settings like port numbers.
•Certificate System Agent's Guide details how to perform agent operations for the CA, RA, DRM, and
TPS subsystems through the Certificate System agent services interfaces.
•Certificate System Command-Line Tools Guide covers the command-line scripts supplied with Red
Hat Certificate System.
•
Chapter 1. About This Guide
4

Managing Smart Cards with the Enterprise Security Client explains how to install, configure, and use
the Enterprise Security Client, the user client application for managing smart cards, user certificates,
and user keys.
•Certificate System Migration Guides cover version-specific procedures for migrating from older ver-
sions of Certificate System to Red Hat Certificate System 7.3.
•Release Notes contains important information on new features, fixed bugs, known issues and work-
arounds, and other important deployment information for Red Hat Certificate System 7.3.
For the latest information about Red Hat Certificate System, including current release notes, complete
product documentation, technical notes, and deployment information, see ht-
tp://1www.redhat.com/1docs/1manuals/1cert-system/.
1.5. Giving Feedback
If there is any error in this Agent's Guide or there is any way to improve the documentation, please let
us know. Bugs can be filed against the documentation for Red Hat Certificate System through Bug-
zilla, http://1bugzilla.redhat.com/1bugzilla. Make the bug report as specific as possible, so we can be
more effective in correcting any issues:
•Select the Red Hat Certificate System product.
•Set the component to Doc - agents-guide.
•Set the version number to 7.3.
•For errors, give the page number (for the PDF) or URL (for the HTML), and give a succinct descrip-
tion of the problem, such as incorrect procedure or typo.
For enhancements, put in what information needs to be added and why.
•Give a clear title for the bug. For example, "Incorrect command example for setup
script options" is better than "Bad example".
We appreciate receiving any feedback — requests for new sections, corrections, improvements, en-
hancements, even new ways of delivering the documentation or new styles of docs. You are welcome
to contact Red Hat Content Services directly at [email protected].
1.6. Document History
Revision History
Revision 7.3.6 August 3, 2009 Ella Deon
Lackey[email protected]
Giving Feedback
5

Correcting labels in the request flow diagram, per Bugzilla #510552.
Revision 7.3.5 June 13, 2009 Ella Deon
Lackey[email protected]
Removing references to the CS SDK and Java SDK, per Bugzilla #491405.
Revision 7.3.4 January 29, 2009 Ella Deon
Lackey[email protected]
Added port separation parameters and usage to pkicreate for Errata RHSA-2009:0007.
Updated examples and formatting section to define default ports used in examples.
Revision 7.3.3 Wed Jun 6 2007 DavidO'Briendav-
[email protected]
Bugzilla 240247. Revised screenshots for presentation and clarity.
Updated information for key recovery and DRM.
Revision 7.3.2 Tue Jun 5 2007 DavidO'Briendav-
[email protected]
Bugzilla 240246. Updated list of available certificate profiles.
Revision 7.3.1 Thu May 11 2007 DavidO'Briendav-
[email protected]
Layout and presentation revision
Grammar, spelling and readability updates.
Revision 7.3.0 Sun May 06 2007 DavidO'Briendav-
[email protected]
Added Revision History.
Minor grammar and style fixes.
Chapter 1. About This Guide
6

Agent Services
This chapter describes the role of the privileged users, agents, in managing Certificate System sub-
systems. It also introduces the tools that agents use to administer service requests.
2.1. Overview of Certificate System
The Red Hat Certificate System is a highly configurable set of software components and tools for cre-
ating, deploying, and managing certificates. The standards and services that facilitate the use of pub-
lic-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, 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 ini-
tiates 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, 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 can exist 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 veri-
fication, such as an interview or notarized documents, while enrollment for others may be fully auto-
mated.
2.1.1. Certificate System Sub-systems
To meet the widest possible range of configuration requirements, the Certificate System permits inde-
pendent installation of five separate subsystems, or managers, that play distinct roles:
Certificate Manager
A Certificate Manager (CM) functions as a root or subordinate CA. This subsystem issues, renews,
and revokes certificates and generates certificate revocation lists (CRLs). It can also publish certific-
ates, files, and CRLs to an LDAP directory, to files, and to an Online Certificate Status Protocol
(OCSP) responder.
The CM can process requests manually (with agent action) or automatically (based on customizable
profiles). Publishing tasks can only be performed by the CM.
The CM also has a built-in OCSP service, enabling OCSP-compliant clients to query the CM directly
about the revocation status of a certificate that it has issued. In certain PKI deployments, it might be
convenient to use the CM's built-in OCSP service, instead of an OCSM.
Because CAs can delegate some responsibilities to subordinate CAs, a CM might share its load
among one or more levels of subordinate CMs.
Subsystems can also be cloned. All clones use the same keys and certificates as the master, which
means that the master and clones essentially all function as a single CA. Many complex deployment
Chapter 2.
7

scenarios are possible.
Data Recovery Manager
A Data Recovery Manager (DRM) oversees the long-term archival and recovery of private encryption
keys for end entities. A CM or TPS can be configured to archive end entities' private encryption keys
with a DRM as part of the process of issuing new certificates.
The DRM 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 sup-
ports dual key pairs; two separate key pairs, one for encryption and one for digital signatures. It is also
possible to perform server-side key generation using the TPS server when enrolling smart cards.
Note
The DRM archives encryption keys. It does not archive signing keys, since archiving
signing keys would undermine the non-repudiation properties of dual-key certificates.
Online Certificate Status Manager
An Online Certificate Status Manager (OCSM) works as an online certificate validation authority and
allows OCSP-compliant clients to verify certificates' current status. The OCSM can receive CRLs from
multiple CMs; clients then query the OCSM for the revocation status of certificates issued by all CMs.
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 OCSM, allowing all clients in the PKI deployment to verify the
revocation status of a certificate by querying a single OCSM.
Note
An online certificate-validation authority is often referred to as an OCSP responder.
Token Key Service
The Token Key Service (TKS) manages the master and transport keys required to generate and dis-
tribute keys for smart cards. The TKS provides security between tokens and the TPS because it pro-
tects the integrity of the master key and token keys.
Token Processing System
The Token Processing System (TPS) acts as a registration authority for authenticating and processing
smart card enrollment requests, PIN reset requests, and formatting requests from the Enterprise Se-
curity Client.
Chapter 2. Agent Services
8

2.1.2. Certificate System Users
Three kinds of users can access Certificate System subsystems: administrators, agents, and end entit-
ies. Administrators are responsible for the initial setup and ongoing maintenance of the subsystems.
Administrators can also assign agent status to users. Agents manage day-to-day interactions with end
entities, which can be users or servers and clients, and other aspects of the PKI. End entities must ac-
cess a Certificate Manager (CM) subsystem to enroll for certificates in a PKI deployment and for certi-
ficate maintenance, such as renewal or revocation.
Figure 2.1, “The Certificate System and Users” shows the ports used by administrators, agents, and
end entities. All agent and administrator interactions with Certificate System subsystems occur over
HTTPS. End-entity interactions can take place over HTTP or HTTPS.
Certificate System Users
9

Figure 2.1. The Certificate System and Users
2.2. Agent Tasks
The designated agents for each subsystem are responsible for the everyday management of end en-
tity requests and other aspects of the PKI:
Certificate Manager Agent
Certificate Manager (CM) agents manage certificate requests received by the CM subsystem,
Chapter 2. Agent Services
10

maintain and revoke certificates as necessary, and maintain global information about certificates.
Data Recovery Manager Agent
Data Recovery Manager (DRM) agents initiate the recovery of lost keys and can obtain informa-
tion about key service requests and archived keys.
Note
Recovering lost or archived key information is done automatically in smart card deploy-
ments because the TPS server is a DRM agent. Smart cards are marked as lost in the
TPS agent page, and then another smart card is later used to recover the old encryp-
tion keys automatically during certificate enrollment.
Online Certificate Status Manager Agent
Online Certificate Status Manager (OCSM) agents can perform tasks such as:
•Checking which CAs are currently configured to publish their CRLs to the OCSM.
•Identifying a CM to the OCSM.
•Adding CRLs directly to the OCSM.
•Viewing the status of OCSP service requests submitted by OCSP-compliant clients.
Token Processing System Agent
Token Processing System (TPS) agents can perform tasks such as:
•Viewing smart card enrollment and formatting activities.
•Listing tokens in the token database.
•Editing token information.
•Deleting tokens from the token database
•Marking tokens as permanently lost, temporarily lost, or damaged.
Token Key Service Agent
There is no direct interface for Token Key Service (TKS) agents to interact with the system.
However, TKS agents can provide the secure communications channel through the TPS server re-
quired for smart card operations through the token management system. The allowed smart card
operations are similar to those for TPS agents.
The privileged operations of an agent are performed through the Certificate System agent services
pages. For a user to access these pages, the user must have a personal SSL client certificate and
have been identified as a privileged user in the user database by the Certificate System administrator.
For more information on creating privileged users, see the Certificate System Administrator's Guide.
Agent Tasks
11

•Section 2.2.1, “Certificate Manager Agent Services”
•Section 2.2.2, “Data Recovery Manager Agent Services”
•Section 2.2.3, “Online Certificate Status Manager Agent Services”
•Section 2.2.4, “Token Processing System Agent Services”
2.2.1. Certificate Manager Agent Services
The default entry page for (CM) agent services is shown in Figure 2.2, “Certificate Manager Agent Ser-
vices Page”. Only designated CM agents, with a valid certificate installed in their client software, are
authorized to access these pages.
Figure 2.2. Certificate Manager Agent Services Page
A CM agent performs the following tasks:
•Handles certificate requests.
An agent can list the certificate service requests received by the CM subsystem, assign requests,
reject or cancel requests, and approve requests for certificate enrollment. See Chapter 4, CA: Hand-
ling Certificate Requests.
•Finds certificates.
Chapter 2. Agent Services
12

Certificates can be searched for individually or searched and listed by different criteria. The details
for all returned certificates are then displayed. See Chapter 5, CA: Finding and Revoking Certific-
ates.
•Revokes certificates.
If a user's key is compromised, the certificate must be revoked to ensure that the key is not mis-
used. Certificates belonging to users who have left the organization may also need revoked. CM
agents can find and revoke a specific certificate or a set of certificates. Users can also request that
their own certificates be revoked. See Section 5.4, “Revoking Certificates”.
•Updates the CRL.
The CM maintains a public list of revoked certificates, called the Certificate Revocation List (CRL).
The list is usually maintained automatically, but, when necessary, the CM agent services page can
be used to update the list manually. See Section 5.5.2, “Updating the CRL”.
•Publishes certificates to a directory.
The Certificate System can be configured to publish certificates and CRLs to an LDAP directory.
This information is usually published automatically, but the CM agent services page can be used to
update the directory manually. See Section 6.2, “Manual Directory Updates”.
•Manages certificate profiles.
The agent can enable and disable certificate profiles. A profile must be temporarily disabled before
an administrator can make changes to the profile itself using the administrative interface. After the
changes have been made, the agent can re-enable the profile for regular use. See Chapter 3, CA:
Working with Certificate Profiles.
2.2.2. Data Recovery Manager Agent Services
The default entry page to the Data Recovery Manager (DRM) agent services is shown in Figure 2.3,
“Data Recovery Manager Agent Services Page”. Only designated DRM agents, with a valid certificate
in their client software, are authorized to access these pages.
Data Recovery Manager Agent Services
13

Figure 2.3. Data Recovery Manager Agent Services Page
A DRM agent performs the following tasks:
•Lists key recovery requests from end entities.
•Lists or searches for archived keys.
•Recovers private data-encryption keys.
•Authorizes and approves key recovery requests.
Key recovery requires the authorization of one or more recovery agents. The DRM administrator
designates recovery agents. Typically, several recovery agents are required to approve key recov-
ery requests in the DRM, so DRM administrators should designate more than one agent.
For more information on these tasks, see Chapter 7, DRM: Recovering Encrypted Data.
2.2.3. Online Certificate Status Manager Agent Services
The default entry page to the Online Certificate Status Manager (OCSM) agent services is shown in
Figure 2.4, “Online Certificate Status Manager Agent Services Page”. Only designated OCSM agents,
with a valid certificate in their client software, are authorized to access these pages.
Chapter 2. Agent Services
14