Redhat CERTIFICATE SYSTEM 8, SYSTEM 8 User Manual

Red Hat Certificate

System 8

Install Guide

Ella Deon Lackey

Publication date: July 22, 2009, updated on March 25, 2010

Install Guide

Red Hat Certificate System 8 Install Guide

The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

All other trademarks are the property of their respective owners.

1801 Varsity Drive Raleigh, NC 27606-2072 USA Phone: +1 919 754 3700 Phone: 888 733 4281 Fax: +1 919 754 3701 PO Box 13588 Research Triangle Park, NC 27709 USA

About This Guide vii

1. Examples and Formatting .............................................................................................. vii

1.1. Formatting for Examples and Commands ............................................................. vii

1.2. Tool Locations .................................................................................................... vii

1.3. Guide Formatting ................................................................................................ vii

2. Additional Reading ........................................................................................................ viii

3. Giving Feedback ............................................................................................................ ix

4. Document History ............................................................................................................ x

1. Overview of Certificate System Subsystems 1

1.1. Subsystems for Managing Certificates ........................................................................... 1

1.1.1. Certificate Manager ........................................................................................... 3

1.1.2. Registration Authority ......................................................................................... 3

1.1.3. Data Recovery Manager .................................................................................... 3

1.1.4. Online Certificate Status Manager ...................................................................... 4

1.2. Subsystems for Managing Tokens ................................................................................. 4

1.2.1. Token Processing System .................................................................................. 5

1.2.2. Token Key Service ............................................................................................ 5

1.2.3. Enterprise Security Client ................................................................................... 5

1.3. Planning the Installation ................................................................................................ 6

2. Prerequisites Before Installing Certificate System 9

2.1. Supported Platforms, Hardware, and Programs .............................................................. 9

2.1.1. Supported Platforms .......................................................................................... 9

2.1.2. Supported Web Browsers .................................................................................. 9

2.1.3. Supported Smart Cards ................................................................................... 10

2.1.4. Supported HSM ............................................................................................... 10

2.1.5. Supported Charactersets .................................................................................. 10

2.2. Required Programs, Dependencies, and Configuration ................................................. 11

2.2.1. Java Development Kit (JDK) ............................................................................ 11

2.2.2. Apache ........................................................................................................... 11

2.2.3. Red Hat Directory Server ................................................................................. 12

2.2.4. Additional Packages ........................................................................................ 12

2.2.5. Firewall Configuration and iptables ................................................................... 13

2.2.6. SELinux Settings ............................................................................................. 13

2.3. Packages Installed on Red Hat Enterprise Linux .......................................................... 13

2.4. Required Information for Subsystem Configuration ....................................................... 15

2.5. Setting up Tokens for Storing Certificate System Subsystem Keys and Certificates .......... 16

2.5.1. Types of Hardware Tokens ............................................................................... 16

2.5.2. Using Hardware Security Modules with Subsystems .......................................... 17

2.5.3. Viewing Tokens ............................................................................................... 21

2.5.4. Detecting Tokens ............................................................................................. 21

3. Installation and Configuration 23

3.1. Overview of Installation ............................................................................................... 23

3.2. Installing the Certificate System Packages ................................................................... 25

3.2.1. Installing through yum ...................................................................................... 25

3.2.2. Installing from an ISO Image ............................................................................ 27

3.3. Configuring a CA ........................................................................................................ 27

3.4. Configuring an RA ...................................................................................................... 36

3.5. Configuring a DRM, OCSP, or TKS ............................................................................. 43

3.6. Configuring a TPS ...................................................................................................... 50

iii

Install Guide

4. Additional Installation Options 61

4.1. Requesting Subsystem Certificates from an External CA ............................................... 61

4.2. Installing a CA with ECC Enabled ............................................................................... 64

4.2.1. Loading a Third-Party ECC Module .................................................................. 64

4.2.2. Loading the Certicom ECC Module ................................................................... 65

4.3. Changing the Hashing Algorithm Used for Subsystem Keys .......................................... 69

4.4. Enabling IPv6 for a Subsystem ................................................................................... 70

4.5. Configuring Separate RA Instances ............................................................................. 71

5. Creating Additional Subsystem Instances 75

5.1. About pkicreate .......................................................................................................... 75

5.2. Running pkicreate for a Single SSL Port ...................................................................... 77

5.3. Running pkicreate with Port Separation ....................................................................... 78

6. Cloning Subsystems 79

6.1. About Cloning ............................................................................................................ 79

6.1.1. Cloning for CAs ............................................................................................... 80

6.1.2. Cloning for DRMs ............................................................................................ 81

6.1.3. Cloning for Other Subsystems .......................................................................... 81

6.1.4. Cloning and Key Stores ................................................................................... 81

6.1.5. Cloning Considerations .................................................................................... 82

6.2. Exporting Keys from a Software Database ................................................................... 82

6.3. Cloning a CA ............................................................................................................. 82

6.4. Cloning OCSP Subsystems ........................................................................................ 85

6.5. Cloning DRM and TKS Subsystems ............................................................................ 88

6.6. Converting Masters and Clones .................................................................................. 90

6.6.1. Converting CA Clones and Masters .................................................................. 90

6.6.2. Converting OCSP Clones ................................................................................. 92

6.7. Updating CA Clones ................................................................................................... 92

7. Silent Configuration 95

7.1. About pkisilent ............................................................................................................ 95

7.2. Silently Configuring Subsystem ................................................................................... 99

7.3. Cloning a Subsystem Silently .................................................................................... 102

7.4. Performing Silent Configuration Using an External CA ................................................ 102

8. Updating and Removing Subsystem Packages 105

8.1. Updating Certificate System Packages ....................................................................... 105

8.2. Uninstalling Certificate System Subsystems ............................................................... 106

8.2.1. Removing a Subsystem Instance .................................................................... 106

8.2.2. Removing Certificate System Subsystem Packages ......................................... 107

9. Using Certificate System 109

9.1. Starting the Certificate System Console ..................................................................... 109

9.2. Starting, Stopping, and Restarting an Instance ........................................................... 109

9.3. Starting the Subsystem Automatically ........................................................................ 109

9.4. Finding the Subsystem Web Services Pages ............................................................. 111

9.5. Default File and Directory Locations for Certificate System .......................................... 114

9.5.1. Default CA Instance Information ..................................................................... 115

9.5.2. Default RA Instance Information ..................................................................... 116

9.5.3. Default DRM Instance Information .................................................................. 116

9.5.4. Default OCSP Instance Information ................................................................. 117

9.5.5. Default TKS Instance Information .................................................................... 118

9.5.6. Default TPS Instance Information .................................................................... 118

9.5.7. Shared Certificate System Subsystem File Locations ....................................... 119

Index 121

About This Guide

This guide explains how to install and configure Red Hat Certificate System subsystems, as well as covering some basic administrative tasks and advanced installation techniques. This guide also lists the supported platforms and dependencies for Red Hat Certificate System; for other information, see the Release Notes.

The Certificate System Deployment Guide explains different usage scenarios, and it is a good idea to understand the major concepts in that guide before installing the Certificate System subsystems. The Certificate System Administrator's Guide covers all of the administrative tasks of Red Hat Certificate System, such as configuring logging, setting up certificate and CRL publishing, requesting and issuing certificates, and building CRLs.

Certificate System agents should refer to the Certificate System Agent's Guide for information on performing agent tasks, such as handling certificate requests and revoking certificates. For information on using Certificate System to manage smart cards and security tokens, see Managing Smart Cards with the Enterprise Security Client.

1. Examples and Formatting

1.1. Formatting for Examples and Commands

All of the examples for Red Hat Certificate System commands, file locations, and other usage are given for Red Hat Enterprise Linux 5 (32-bit) systems. Be certain to use the appropriate commands and files for your platform.

To start the Red Hat Certificate System:

service pki-ca start

Example 1. Example Command

1.2. Tool Locations

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

Monospace with a background

vii

About This Guide

Formatting Style Purpose

Italicized text Any text which is italicized is a variable, such as

Bolded text Most phrases which are in bold are application names, such as

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

2. Additional Reading

The documentation for Certificate System includes the following guides:

• Certificate System Deployment Guide1 describes basic PKI concepts and gives an overview of the planning process for setting up Certificate System.

This manual is intended for Certificate System administrators.

• Certificate System Installation Guide2 covers the installation process for all Certificate System subsystems.

This manual is intended for Certificate System administrators.

• Certificate System Administrator's Guide3 explains all administrative functions for the Certificate System. Administrators maintain the subsystems themselves, so this manual details backend configuration for certificate profiles, publishing, and issuing certificates and CRLs. It also covers managing subsystem settings like port numbers, users, and subsystem certificates.

This manual is intended for Certificate System administrators.

• Certificate System Agent's Guide4 describes how agents — users responsible for processing certificate requests and managing other aspects of certificate management — can use the Certificate System subsystems web services pages to process certificate requests, key recovery, OCSP requests and CRLs, and other functions.

viii

Giving Feedback

This manual is intended for Certificate System agents.

• Managing Smart Cards with the Enterprise Security Client5 explains how to install, configure, and use the Enterprise Security Client, the user client application for managing smart cards, user certificates, and user keys.

This manual is intended for Certificate System administrators, agents, privileged users (such as security officers), and regular end users.

• Using End User Services6 is a quick overview of the end-user services in Certificate System, a simple way for users to learn how to access Certificate System services.

This manual is intended for regular end users.

• Certificate System Command-Line Tools Guide7 covers the command-line scripts supplied with Red Hat Certificate System.

This manual is intended for Certificate System administrators.

• Certificate System Migration Guide8 covers version-specific procedures for migrating from older versions of Certificate System to Red Hat Certificate System 8.0.

This manual is intended for Certificate System administrators.

• Release Notes9 contains important information on new features, fixed bugs, known issues and workarounds, and other important deployment information for Red Hat Certificate System 8.0.

All of the latest information about Red Hat Certificate System and both current and archived documentation is available at http://www.redhat.com/docs/manuals/cert-system/.

3. Giving Feedback

If there is any error in this Installation 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 Bugzilla, http://bugzilla.redhat.com/bugzilla. 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 - quick install guide.

• Set the version number to 8.0.

• For errors, give the page number (for the PDF) or URL (for the HTML), and give a succinct description 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, enhancements, even new ways of delivering the documentation or new styles of docs. You are welcome to contact Red Hat Content Services directly at docs@redhat.com.

About This Guide

4. Document History

Revision

8.0.10

Adding information on new end-entities client authentication port for the CA, related to the MitM resolution in Errata RHBA-2010:0169.

Revision 8.0.9 February 18, 2009 Ella Deon Lackey dlackey@redhat.com

Changing LunaSA setup, per Bugzilla 537529. Correcting the cs_port definition, per Bugzilla 533303.

Revision 8.0.8 December 21, 2009 Ella Deon Lackey dlackey@redhat.com

Updating platform support to include 64-bit Windows platforms, per Errata RHBA-2009:1687.

Revision 8.0.7 November 25, 2009 Ella Deon Lackey

Updating the pkisilent documentation and expanding the CA configuration section to add ability to specify the CA siging algorithm at installation, per Errata RHBA-2009:1602.

Revision 8.0.6 November 12, 2009 Ella Deon Lackey

Updating the Certicom ECC configuration per comment #3 in Bugzilla 507428. Correcting the 'rpm -qi' example in checking prerequisites, per QE feedback. Adding note about (no) 64-bit support for ESC.

Revision 8.0.5 November 3, 2009 Ella Deon Lackey

Adding information on setting the NSS_USE_DECODED_CKA_EC_POINT environment variable for the console and clarifying the security database argument in the modutil step for configuring the Certicom ECC module.

Revision 8.0.4 August 28, 2009 Ella Deon Lackey

Removing the draft watermarks. Tech reviews for chapter 2 (prerequisites) and chapter 9 (basic usage), per Bugzilla #510578 and #510587.

Revision 8.0.3 August 11, 2009 Ella Deon Lackey

March 25, 2010 Ella Deon Lackey dlackey@redhat.com

Tech reviews for chapter 8, per Bugzilla #510586. Adding extra bullet point on using unique certificate nicknames for HSMs, related to Bugzilla #510987.

Revision 8.0.2 August 3, 2009 Ella Deon Lackey

Tech reviews for chapter 4, per Bugzilla #510580.

Revision 8.0.1 July 26, 2009 Ella Deon Lackey

Tech reviews for chapters 1, 3, 5, 6, and 7, per Bugzilla #510577, #510579, #510581, #510582, #510585. Adding a section for configuring netHSM to work with SELinux, per Bugzilla #513312, with cross references in the instance configuration sections.

Revision 8.0.0 July 22, 2009 Ella Deon Lackey

Initial draft for Certificate System 8.0 Installation Guide.

Chapter 1.

Overview of Certificate System Subsystems

Red Hat Certificate System is a highly configurable set of components which create and manage certificates and keys at every point of the certificate lifecycle. Certificate System is based on open standards so that it effectively creates a scalable, customizable, and robust public-key infrastructure (PKI).

Certificate System has subsystems which discretely handle different PKI management functions. These subsystems interact in flexibly established ways to manage certificates and to manage tokens.

1.1. Subsystems for Managing Certificates

Up to four Certificate System subsystems work together to manage certificates:

• Certificate Manager, a certificate authority (CA) which issues, renews, and revokes certificates and publishes certificate revocation lists (CRLs)

• Data Recovery Manager (DRM), which archives and recovers keys

• Online Certificate Status Manager (OCSP), which processes requests for certificates' revocation status

• Registration Authority (RA), which validates and approves certificate requests locally and then forwards approval to the CA to issue the certificates

Chapter 1. Overview of Certificate System Subsystems

The core of the Certificate System is the Certificate Manager. This is the only required subsystem and handles the actual certificate management tasks. The other subsystems can be added for additional functionality (the DRM) or to move the load for some common operations off of the CA, such as using an OCSP for status requests and an RA to process certificate requests.

The CA, RA, DRM, and OCSP are the subsystems used to manage certificates, keys, and CRLs, through every step of the cycle of a certificate:

1. Generating a certificate request (CA or RA)

2. Submitting the request to a CA (CA or RA)

3. Generating key pairs (CA)

4. Storing the key pairs (DRM)

5. Issuing the certificate (CA)

6. Recovering the keys if the certificate is lost (DRM)

Certificate Manager

7. Revoking the certificate (CA)

8. Checking whether the certificate is revoked or active when an entity tries to use the certificate for

authentication (OCSP)

All of the subsystems (CA, RA, DRM, and OCSP, as well as the token subsystems) are organized together in security domains. Security domains define communication between subsystems, and this makes the Certificate System very efficient. For example, if a user needs to archive keys, the request can be processed by the first available DRM in the domain, automatically. The available DRMs in the domain are automatically updated every time a new DRM is configured.

1.1.1. Certificate Manager

The Certificate Manager subsystem is a certificate authority. It issues, renews, revokes, and publishes a wide variety of certificates: for servers, for users, for routers, for other subsystems, and for file or object signing. The Certificate Manager also compiles and publishes CRLs.

Certificate Managers can be structured in series (hierarchy), so that one Certificate Manager sets policies and issues signing certificates to a subordinate CA. The highest Certificate Manager in the chain is a root CA.

A special kind of certificate is used by CAs to sign certificates they issue, sort of like a stamp or seal. This is called a CA signing certificate. A subordinate CA is issued a CA signing certificate by a CA higher in the hierarchy, and the parameters of the CA signing certificate are set by the superior CA. A CA which issues its own signing certificate has a self-signed certificate. There are benefits to having a self-signed CA certificate for your root CA, as well as some benefits to having the certificate signed by a third-party CA.

Additionally, a Certificate Manager is always the subsystem which works as the registry for the security domain. The very first Certificate Manager configured must create a security domain, but every Certificate Manager configured after has the option of joining an existing security domain rather than creating a new one. The configuration of your PKI deployment determines whether you need multiple security domains; for more information, see the Red Hat Certificate System Deployment Guide.

1.1.2. Registration Authority

The Registration Authority subsystem handles certain certificate issuing tasks locally, such as generating and submitting certificate requests. This effectively makes the RA a load-balancer for the CA; a local RA can receive and verify the legitimacy of a certificate request (authenticate it) and then forward valid requests to the CA to issue the certificate. Certificates can also be retrieved through the RA and the status of the request can be checked through the RA, both of which lower demand on the CA.

The RA is normally set up outside of the firewall, and the CA is set up behind the firewall so that requests can be submitted to Certificate System externally, while the CA is protected.

The RA accepts requests for a smaller number of certificate types than the CA, including user, server, and router certificates.

1.1.3. Data Recovery Manager

The Data Recovery Manager (DRM) is a key recovery authority, which means it works with the Certificate Manager when a certificate is issued and stores private encryption keys. Those private keys can be restored (in a PKCS #12 file) if a certificate is lost.

Chapter 1. Overview of Certificate System Subsystems

NOTE

The DRM only archives encryption keys, not signing keys, because that compromises the non-repudiation properties of signing keys. Non-repudiation means that a user cannot deny having performed some action, such as sending an encrypted email, because they are the only possessor of that key.

1.1.4. Online Certificate Status Manager

The Online Certificate Status Manager is an OCSP service, external to the Certificate Manager. Although the Certificate Manager is configured initially with an internal OCSP service, an external OCSP responder allows the OCSP subsystem to be outside the firewall and accessible externally, while keeping the Certificate Manager behind the firewall. Like the RA, the OCSP acts as a loadbalancer for requests to the Certificate Manager.

The Online Certificate Status Manager verifies the status of a certificate by checking a certificate revocation list, published by the Certificate Manager, to see if the specified certificate has been revoked. More than one Certificate Manager can publish CRLs to a single OCSP.

1.2. Subsystems for Managing Tokens

Two subsystems are required to manage tokens:

• Token Processing System (TPS), which accepts operations from a token and forwards them to the CA (for processing certificate requests, renewal, issuing, and revocation) and to the DRM (to archive or restore keys)

• Token Key Service (TKS), which generates master keys and symmetric keys for the TPS to use when communicating with other subsystems

A third application, the Enterprise Security Client, is the interface between the user and the TPS.

Token Processing System

1.2.1. Token Processing System

The Token Processing System (TPS) is the conduit between the user-centered Enterprise Security Client, which interacts with the tokens, and the Certificate System backend subsystems, such as the Certificate Manager. The TPS is required in order to manage smart cards.

The TPS communicates with the CA and DRM for processing token operations. The TPS also communicates with the TKS to derive token-specific secret keys.

1.2.2. Token Key Service

The Token Key Service (TKS) uses a master key to derive specific, separate keys for every smart card. The TPS uses these secret keys to communicate with each smart card securely, since all communication between the TPS and the smart card is encrypted.

The only Certificate System subsystem which the TKS interacts with is the TPS.

1.2.3. Enterprise Security Client

The Enterprise Security Client is not a subsystem since it does not perform any operations with certificates, keys, or tokens. The Enterprise Security Client, as the name implies, is a user interface which allows people to manage certificates on smart cards very easily. The Enterprise Security Client sends all token operations, such as certificate requests, to the TPS, which then sends them to the CA.

Chapter 1. Overview of Certificate System Subsystems

1.3. Planning the Installation

Before beginning to install and configure the Certificate System subsystems, determine what the organization of the PKI is.

Q: What types of subsystems do you need to install?

A: This depends on the kind of functionality you need and the load you expect to have. There

are several different kinds of subsystems for managing certificates (Section 1.1, “Subsystems

for Managing Certificates”) and for managing tokens (Section 1.2, “Subsystems for Managing Tokens”).

Q: How many subsystems do you need to install?

A: This depends very much on the expected load and also on geographical or departmental

divisions. Subsystems can be cloned, meaning they essentially are clustered, operating as a single unit, which is good for load balancing and high availability. Additionally, security domains create trusted relationships between subsystems, allowing them to work together to find available subsystems to respond to immediate needs. Multiple security domains can be used in a single PKI, with multiple instances of any kind of subsystem.

Q: Will the subsystem certificates and keys be stored on the internal software token in

Certificate System or on an external hardware token?

A: Certificate System supports two hardware security modules (HSM): nCipher netHSM 2000 and

Safenet LunaSA. Using a hardware token can require additional setup and configuration before installing the subsystems, but it also adds another layer of security.

Q: What machines should the subsystem be installed on?

A: This depends on the network design. The RA and OCSP subsystems are specifically designed

to operate outside a firewall for user convenience, while the CA, DRM, and TPS should all be secured behind a firewall.

Q: To what security domain should a subsystem instance be added?

A: Because the subsystems within a security domain have trusted relationships with each other, it is

important what domain a subsystem joins. Security domains can have different certificate issuing policies, different kinds of subsystems within them, or a different Directory Server database. Map out where (both on the physical machine and in relation to each other) each subsystem belongs, and assign it to the security domain accordingly.

Q: Should a subsystem be cloned?

A: Cloned subsystems work together, essentially as a single instance. This can be good for high

demand systems, failover, or load balancing, but it can become difficult to maintain. For example, cloned CAs have serial number ranges for the certificates they issue, and a clone could hit the end of its range.

Q: Should the Certificate Manager be a self-signed root CA or a subordinate CA?

Planning the Installation

A: A Certificate Manager can be configured as either a root CA or a subordinate CA. The difference

between a root CA and a subordinate CA is who signs the CA signing certificate. A root CA signs its own certificate. A subordinate CA has another CA (either internal or external) sign its certificate.

A self-signing root CA issues and signs its own CA signing certificate. This allows the CA to set its own configuration rules, like validity periods and the number of allowed subordinate CAs.

A subordinate CA has its certificates issued by a public CA or another Certificate System root CA. This CA is subordinate to the other CA's rules about its certificate settings and how the certificate can be used, such as the kinds of certificates that it can issue, the extensions that it is allowed to include in certificates, and the levels of subordinate CAs the subordinate CA can create.

One option is to have the Certificate manager subordinate to a public CA. This can be very restrictive, since it introduces the restrictions that public CAs place on the kinds of certificates the subordinate CA can issue and the nature of the certificate chain. On the other hand, one benefit of chaining to a public CA is that the third party is responsible for submitting the root CA certificate to a web browser or other client software, which is a major advantage for certificates that are accessed by different companies with browsers that cannot be controlled by the administrator.

The other option is make the CA subordinate to a Certificate System CA. Setting up a Certificate System CA as the root CA means that the Certificate System administrator has control over all subordinate CAs by setting policies that control the contents of the CA signing certificates issued.

It is easiest to make the first CA installed a self-signed root, so that it is not necessary to apply to a third party and wait for the certificate to be issued. Make sure that you determine how many root CAs to have and where both root and subordinate CAs will be located.

Chapter 2.

Prerequisites Before Installing Certificate System

Before installing the Red Hat Certificate System subsystems, check out the requirements and dependencies for the specific platform, as well as looking at the installed packages.

2.1. Supported Platforms, Hardware, and Programs

2.1.1. Supported Platforms

The Certificate System subsystems (CA, RA, DRM, OCSP, TKS, and TPS) are supported on the following platforms:

• Red Hat Enterprise Linux 5.3 (x86, 32-bit)

• Red Hat Enterprise Linux 5.3 (x86_64, 64-bit)

The Enterprise Security Client, which manages smart cards for end users, is supported on the following platforms:

• Red Hat Enterprise Linux 5.3 (x86, 32-bit)

• Red Hat Enterprise Linux 5.3 (x86_64, 64-bit)

• Microsoft Windows Vista 32-bit

• Microsoft Windows Vista 64-bit

• Microsoft Windows XP 32-bit

• Microsoft Windows XP 64-bit

2.1.2. Supported Web Browsers

The services pages for the subsystems require a web browser that supports SSL. It is strongly recommended that users such as agents or administrators use Mozilla Firefox to access the agent services pages. Regular users should use Mozilla Firefox or Microsoft Internet Explorer.

NOTE

The only browser that is fully-supported for the HTML-based instance configuration wizard is Mozilla Firefox.

Platform Agent Services End User Pages

Red Hat Enterprise Linux Firefox 3.x Firefox 3.x

Windows Vista Firefox 2.x Firefox 2.x

Internet Explorer 7 and higher

Windows XP Firefox 2.x Firefox 2.x

Chapter 2. Prerequisites Before Installing Certificate System

Platform Agent Services End User Pages

Internet Explorer 6 and higher

Mac OS 10.x Agent services are not

supported for Mac

Table 2.1. Supported Web Browsers by Platform

Firefox 2.x

2.1.3. Supported Smart Cards

The Enterprise Security Client supports Global Platform 2.01-compliant smart cards and JavaCard 2.1 or higher.

The Certificate System subsystems have been tested using the following tokens:

• Gemalto TOP IM FIPS CY2 64K token, both as a smart card and GemPCKey USB form factor key

• Gemalto Cyberflex e-gate 32K token

• Safenet 330J Java smart card

Smart card testing was conducted using the SCM SCR331 CCID reader.

The only card manager applet supported with Certificate System is the CoolKey applet which ships with Red Hat Enterprise Linux 5.3.

2.1.4. Supported HSM

Red Hat Certificate System supports two hardware security modules (HSM), nCipher netHSM 2000 and Chrysalis-IT LunaSA.

HSM Firmware Appliance Software Client Software

Safenet Chrysalis-ITS LunaSA

nCipher netHSM 2000 2.33.60 11.10

4.5.2 3.2.4 3.2.4

2.1.5. Supported Charactersets

Red Hat Certificate System fully supports UTF-8 characters in the CA end users forms for specific fields. This means that end users can submit certificate requests with UTF-8 characters in those fields and can search for and retrieve certificates and CRLs in the CA and retrieve keys in the DRM when using those field values as the search parameters.

Four fields fully-support UTF-8 characters:

• Common name (used in the subject name of the certificate)

• Organizational unit (used in the subject name of the certificate)

• Requester name

• Additional notes (comments appended by the agent to the certificate)

Required Programs, Dependencies, and Configuration

NOTE

This support does not include supporting internationalized domain names, like in email addresses.

2.2. Required Programs, Dependencies, and Configuration

To install any Red Hat Certificate System subsystems on Red Hat Enterprise Linux, three programs are required: OpenJDK, Apache or Tomcat (depending on the subsystem), and Red Hat Directory Server. All other require packages should be present as part of the base Red Hat Enterprise Linux operating system packages.

2.2.1. Java Development Kit (JDK)

Certificate System requires OpenJDK 1.6.0. On Red Hat Enterprise Linux systems, this must be installed separately. The OpenJDK can be installed by using yum or by downloading the packages directly from http://openjdk.java.net/install/. For example:

yum install java-1.6.0-openjdk

After installing the JDK, run /usr/sbin/alternatives as root to insure that the proper JDK is available:

/usr/sbin/alternatives --config java

There are 3 programs which provide 'java'.

Selection Command

---------------------------------------------- 1 /usr/lib/jvm/jre-1.4.2-gcj/bin/java 2 /usr/lib/jvm/jre-1.6.0-openjdk/bin/java *+ 3 /usr/lib/jvm/jre-1.6.0-sun.x86_64/bin/java

See http://kbase.redhat.com/faq/FAQ_54_4667.shtm for more information on using the JDK for Red Hat Certificate System.

2.2.2. Apache

Apache 2.x must be installed in order to install the TPS subsystem. Check that the appropriate version of Apache is installed.

yum info httpd Installed Packages Name : httpd Arch : x86_64 Version: 2.2.3 Release: 22.el5_3.2 Size : 2.9 M Repo : installed ...

Install Apache if it is not already available. For example:

Chapter 2. Prerequisites Before Installing Certificate System

yum install httpd

2.2.3. Red Hat Directory Server

All subsystems require access to Red Hat Directory Server 8.1 on the local machine or a remote machine. This Directory Server instance is used by the subsystems to store their system certificates and user data.

The Directory Server used by the Certificate System subsystems can be installed on Red Hat Enterprise Linux 5.3 32-bit, Red Hat Enterprise Linux 5.3 64-bit, or Solaris 9 Sparc 64-bit, regardless of the system on which Red Hat Certificate System is installed.

Check that the Red Hat Directory Server is already installed. For example:

yum info redhat-ds Installed Packages Name : redhat-ds Arch : x86_64 Version : 8.1.0 Release : 0.14el5dsrv Size : 136M Repo : installed ...

Install and configure Red Hat Directory Server 8.1, if a directory service is not already available. For example:

yum install redhat-ds

setup-ds-admin.pl

Go through the configuration wizard; the default settings are fine for the Certificate System needs.

Installing Red Hat Directory Server is described in more detail in the Red Hat Directory Server Installation Guide.

2.2.4. Additional Packages

The following package groups and packages must be installed on all Red Hat Enterprise Linux systems:

• gnome-desktop (package group)

• compat-arch-support (package group)

• web-server (package group)

• kernel-smp (package)

• e2fsprogs (package)

• firefox (package)

To verify that the packages are installed, just run rpm -qi For example:

rpm -qi gnome-desktop

Firewall Configuration and iptables

gnome-desktop-2.16.0-1.el5

On 64-bit Red Hat Enterprise Linux platforms, be certain that the 64-bit (x86_64) compat-libstdc ++ libraries are installed, and not only the 32-bit (i386) libraries. To confirm this, run the following as root:

rpm -qi compat-libstdc++ --queryformat '%{NAME}-%{VERSION}-%{RELEASE}.%{ARCH}.rpm\n' | grep x86_64

Numerous libraries should be displayed.

2.2.5. Firewall Configuration and iptables

Any firewalls must be configured to allow access to the Certificate System ports and to any other applications, like Red Hat Directory Server, which are required for the operation of the subsystems. Use caution when configuring the firewall, so that the system remains secure. The port numbers for the default instances are listed in Section 9.5, “Default File and Directory Locations for Certificate

System”.

As part of configuring the firewalls, if iptables is enabled, then it must have configured policies to allow communication over the appropriate Certificate System ports. Configuring iptables is described in the Red Hat Enterprise Linux Deployment Guide, such as "Using iptables."1 Installing the subsystems will fail unless iptables is turned on and properly configured.

2.2.6. SELinux Settings

SELinux policies for Certificate System subsystems are installed as a dependency for Certificate System 8.0, in the pki-selinux package. The SELinux policies are automatically configured whenever a new instance is created by the pkicreate command.

Red Hat recommends running Certificate System with SELinux in enforcing mode, to make the most of the security policies.

If SELinux is set to enforcing, then any external modules or hardware which interact with the subsystems must be configured with the proper SELinux settings to proceed with subsystem installation:

• Third-party modules, such as for ECC or HSM, must have an SELinux policy configured for them, or

SELinux needs to be changed from enforcing mode to permissive mode to allow the module to function. Otherwise, any subsystem operations which require the ECC module will fail.

Changing SELinux policies is covered in the Red Hat Enterprise Linux Deployment Guide, such as

chapter 46, "Customizing SELinux Policy2."

• SELinux policies must be set for any nCipher netHSM 2000 modules, as described in

Section 2.5.2.4, “Setting up SELinux on nCiper netHSM 2000”.

2.3. Packages Installed on Red Hat Enterprise Linux

Multiple packages are installed with the Certificate System, in addition to the core Certificate System components.

http://www.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/5.2/html/Deployment_Guide/s1-fireall-ipt-act.html

Chapter 2. Prerequisites Before Installing Certificate System

RPMs for Certificate System Subsystems and Components

osutil pki-kra pki-tks

pki-setup pki-tps

pki-ca pki-migrate

pki-common pki-native-tools symkey

pki-console pki-ocsp

pki-java-tools

RPMs for Tomcat Web Services

ant jakarta-commons-discovery jakarta-oro

avalon-framework jakarta-commons-el regexp

avalon-logkit jakarta-commons-fileupload tomcat5

axis jakarta-commons-httpclient tomcat5-common

bcel jakarta-commons-launcher tomcat5-jasper

classpathx-jaf jakarta-commons-logging tomcat5-server

classpathx-mail jakarta-commons-modeler velocity

eclipse-ecj jakarta-commons-pool werken.xpath

geronimo-specs jdom wsdl4j

xalan-j2

geronimo-specs-compat jakarta-commons-beanutils xerces-j2

jakarta-commons-collections ldapjdk xml-commons

jakarta-commons-daemon log4j xml-commons-apis

jakarta-commons-dbcp mx4j xml-commons-resolver

jakarta-commons-digester

RPMs for Apache Web Services

mod_perl perl-XML-NamespaceSupport

pcre-devel perl-XML-Parser

perl-XML-SAX perl-Parse-RecDescent

tcl perl-XML-Simple

tcl-devel

RPMs for LDAP Support

cyrus-sasl mozldap-devel mozldap-tools

RPMs for SQL Lite Support for the RA

perl-DBD-SQLite perl-DBI sqlite-devel

RPMs for NSS and NSPR

jss

Required Information for Subsystem Configuration

RPMs for NSS and NSPR

nspr

nss

svrcore

2.4. Required Information for Subsystem Configuration

When the Certificate System subsystems are configured, some outside information must be available, as listed in Table 2.2, “Required Information for Configuring Subsystems”.

Information Description

preop.pin parameter in the CS.cfg file in the instance conf/ directory. This is used to log into the configuration wizard.

Security domain information CAs can create a new security domain, which

requires a unique name and a username and password for the CA agent who administers the domain. All other subsystems must join an existing security name. Have the username and password of the CA agent who administers the domain.

CA information If the subsystem is not a CA, then it is necessary

to select a CA from a drop-down menu or add an external CA. If a Certificate System CA is selected, then supply the CA agent username and password.

Subsystem information (for TPS configuration) When installing a TPS, you must have already

configured the other subsystem and have their bind information available:

The CA The TKS (required) The DRM (optional, for server-side key generation)

When configuring the TPS, the TKS and DRM to connect with the TPS are selected from a dropdown list of all subsystems within the security domain.

Directory Server hostname and port number The Certificate System uses the user database

of the Directory Server to store its information, and the hostname and port number of the LDAP directory is required for the Certificate System to access the database.

Directory Manager DN and password The Certificate System must be able to bind to

the user database, so a user ID and password must be supplied to bind to the Directory Server. This user is normally the Directory Manager. The

Chapter 2. Prerequisites Before Installing Certificate System

Information Description

default Directory Manager DN is cn=Directory Manager.

Certificate and key recovery files (for cloning) If the subsystem being configured is a clone of

another subsystem, then the backup files for the master subsystem must be locally accessible.

Table 2.2. Required Information for Configuring Subsystems

2.5. Setting up Tokens for Storing Certificate System

Subsystem Keys and Certificates

A subsystem instance generates and stores its key information in a key store, called a token. A subsystem instance can be configured for the keys to be generated and stored using the internal NSS token or on a separate cryptographic device, a hardware token.

2.5.1. Types of Hardware Tokens

A token is a hardware or software device that performs cryptographic functions and stores public-key certificates, cryptographic keys, and other data. The Certificate System defines two types of tokens, internal and external, for storing key pairs and certificates that belong to the Certificate System subsystems.

2.5.1.1. Internal Tokens

An internal (software) token is a pair of files, usually called the certificate database and key database, that the Certificate System uses to generate and store its key pairs and certificates. The Certificate System automatically generates these files in the filesystem of its host machine when first using the internal token. These files were created during the Certificate System subsystem configuration if the internal token was selected for key-pair generation.

In the Certificate System, the certificate database is named cert8.db; the key database is named key3.db. These files are located in the instanceID/alias directory.

2.5.1.2. External Tokens

An external token refers to an external hardware device, such as a smart card or hardware security module (HSM), that the Certificate System uses to generate and store its key pairs and certificates. The Certificate System supports any hardware tokens that are compliant with PKCS #11.

PKCS #11 is a standard set of APIs and shared libraries which isolate an application from the details of the cryptographic device. This enables the application to provide a unified interface for PKCS #11compliant cryptographic devices.

The PKCS #11 module implemented in the Certificate System supports cryptographic devices supplied by many different manufacturers. This module allows the Certificate System to plug in shared libraries supplied by manufacturers of external encryption devices and use them for generating and storing keys and certificates for the Certificate System managers.

Consider using external tokens for generating and storing the key pairs and certificates used by Certificate System. These devices are another security measure to safeguard private keys because hardware tokens are sometimes considered more secure than software tokens.

Using Hardware Security Modules with Subsystems

Before using external tokens, plan how the external token is going to be used with the subsystem:

• All system keys for a subsystem must be generated on the same token.

• The subsystem keys must be installed in an empty HSM slot. If the HSM slot has previously been used to store other keys, then use the HSM vendor's utilities to delete the contents of the slot. The Certificate System has to be able to create certificates and keys on the slot with default nicknames. If not properly cleaned up, the names of these objects may collide with previous instances.

• A single HSM can be used to store certificates and keys for mulitple subsystem instances, which may be installed on multiple hosts. When an HSM is used, any certificate nickname for a subsystem must be unique for every subsystem instance managed on the HSM.

2.5.1.3. Hardware Cryptographic Accelerators

The Certificate System can use hardware cryptographic accelerators with external tokens. Many of the accelerators provide the following security features:

• Fast SSL connections. Speed is important to accommodate a high number of simultaneous enrollment or service requests.

• Hardware protection of private keys. These devices behave like smart cards by not allowing private keys to be copied or removed from the hardware token. This is important as a precaution against key theft from an active attack of an online Certificate Manager.

2.5.2. Using Hardware Security Modules with Subsystems

The Certificate System supports the nCipher netHSM hardware security module (HSM) by default. Certificate System-supported HSMs are automatically added to the secmod.db database with modutil during the pre-configuration stage of the installation, if the PKCS #11 library modules are in the default installation paths.

During configuration, the Key Store panel displays the supported modules, along with the NSS internal software PKCS #11 module. All supported modules that are detected show a status of Found and is individually marked as either Logged in or Not logged in. If a token is found but not logged in, it is possible to log in using the Login under Operations. If the administrator can log into a token successfully, the password is stored in a configuration file. At the next start or restart of the Certificate System instance, the passwords in the password store are used to attempt a login for each corresponding token.

Administrators are allowed to select any of the tokens that are logged in as the default token, which is used to generate system keys.

2.5.2.1. Adding or Managing the HSM Entry for a Subsystem

When an HSM is selected as the default token, the following parameters are set in instance's CS.cfg file to configure the HSM:

#RHCS supported modules preop.configModules.module0.commonName=NSS Internal PKCS #11 Module preop.configModules.module0.imagePath=../img/mozilla.png preop.configModules.module0.userFriendlyName=NSS Internal PKCS #11 Module preop.configModules.module1.commonName=nfast preop.configModules.module1.imagePath=../img/ncipher.png

Chapter 2. Prerequisites Before Installing Certificate System

preop.configModules.module1.userFriendlyName=nCipher's nFast Token Hardware Module preop.configModules.module2.commonName=lunasa preop.configModules.module2.imagePath=../img/safenet.png preop.configModules.module2.userFriendlyName=SafeNet's LunaSA Token Hardware Module #selected token preop.module.token=Internal Key Storage Token

In addition, the following parameter is set in the password.conf for the HSM password:

hardware-nethsm=caPassword

2.5.2.2. Using Chrysalis LunaSA HSM

To make sure that a LunaSA HSM works with Certificate System, edit the configuration files for the HSM before configuring the subsystems:

1. Check that the LunaSA module has been properly installed:

modutil -dbdir /var/lib/subsystem_name/alias -list

Listing of PKCS #11 Modules

-----------------------------------------------------------

1. NSS Internal PKCS #11 Module slots: 2 slots attached status: loaded

slot: NSS Internal Cryptographic Services token: NSS Generic Crypto Services

slot: NSS User Private Key and Certificate Services token: NSS Certificate DB

2. lunasa library name: /usr/lunasa/lib/libCryptoki2_64.so slots: 1 slot attached status: loaded

slot: LunaNet Slot token: lunasa3-ca

If the LunaSA module isn't listed, then install the module manually:

a. Stop the subsystem.

service subsystem_name stop

b. Load the module.

modutil -dbdir /var/lib/subsystem_name/alias -nocertdb -add lunasa -libfile /usr/ lunasa/lib/libCryptoki2_64.so

c. Verify that the module has been loaded.

modutil -dbdir /var/lib/subsystem_name/alias -list

d. Start the subsystem.

Using Hardware Security Modules with Subsystems

service subsystem_name start

2. Open the /etc/Chrystoki.conf configuration file.

3. Add this configuration parameter.

Misc { NetscapeCustomize=1023; }

4. If they are there, remove these two configuration lines for the applet version.

AppIdMajor=2; AppIdMinor=4;

Then, after going through the subsystem configuration, but before restarting the server when completing the configuration wizard, edit the subsystem configuration to recognize the token:

1. Stop the server.

service subsystem_name stop

2. Edit the instance's serverCertNick.conf file in the /var/lib/subsystem_name/conf

directory. Add the HSM token name to the serverCert parameter.

The original value only points to the server:

Server-Cert instanceID

The new value includes a reference to the LunaSA HSM:

lunasa3-ca:Server-Cert instanceID"

3. Start the server.

service subsystem_name start

2.5.2.3. Installing External Tokens and Unsupported HSM

To use HSMs which are not officially supported by the Certificate System, add the module to the subsystem database manually. If the desired HSM does not appear in the Security Modules panel during the subsystem configuration, check that the HSM is installed and activated correctly. Then run modutil manually to add the module to the secmod.db database.

1. Install the cryptographic device, using the manufacturer's instructions. Be sure to name the token

something that will help identify it easily later.

2. Install the PKCS #11 module using the modutil command-line utility.

a. Open the alias directory for the subsystem which is being configured with the PKCS #11

module. For example:

Chapter 2. Prerequisites Before Installing Certificate System

cd /var/lib/pki-ca/alias

b. The required security module database file, secmod.db, should be created by default when

the subsystem is created. If it does not exist, use the modutil utility to create secmod.db.

modutil -dbdir . -nocertdb -create

c. Use the modutil utility to set the library information.

modutil -dbdir . -nocertdb / -add module_name -libfile library_file

library_file specifies the path to the library file containing the PKCS #11 interface module and module_name gives the name of the PKCS #11 module which was set when the drivers were

installed.

• For the LunaSA HSM:

modutil -dbdir . -nocertdb -add lunasa -libfile /usr/lunasa/lib/libCryptoki2.so

• For an nCipher HSM:

modutil -dbdir . -nocertdb -add nethsm -libfile /opt/nfast/toolkits/pkcs11/ libcknfast.so

2.5.2.4. Setting up SELinux on nCiper netHSM 2000

SELinux policies are created and configured automatically for all Certificate System instances, so Certificate System can run with SELinux in enforcing or permissive modes.

If SELinux is in enforcing mode, than any hardware tokens to be used with the Certificate System instances must also be configured to run with SELinux in enforcing mode, or the HSM will not be available during subsystem installation.

IMPORTANT

SELinux must be configured for the HSM before installing any Certificate System instances.

1. Install the SELinux packages for Certificate System.

yum install pki-selinux

2. Reset the context of files in /dev/nfast to match the newly-installed policy.

/sbin/restorecon -R /dev/nfast

3. Restart the netHSM software.

+ 102 hidden pages

Redhat CERTIFICATE SYSTEM 8, SYSTEM 8 User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Install Guide

About This Guide

1. Examples and Formatting

1.1. Formatting for Examples and Commands

1.2. Tool Locations

1.3. Guide Formatting

2. Additional Reading

3. Giving Feedback

4. Document History

1.1. Subsystems for Managing Certificates

1.1.1. Certificate Manager

1.1.2. Registration Authority

1.1.3. Data Recovery Manager

1.1.4. Online Certificate Status Manager

1.2. Subsystems for Managing Tokens

1.2.1. Token Processing System

1.2.2. Token Key Service

1.2.3. Enterprise Security Client

1.3. Planning the Installation

2.1. Supported Platforms, Hardware, and Programs

2.1.1. Supported Platforms

2.1.2. Supported Web Browsers

2.1.3. Supported Smart Cards

2.1.4. Supported HSM

2.1.5. Supported Charactersets

2.2. Required Programs, Dependencies, and Configuration

2.2.1. Java Development Kit (JDK)

2.2.2. Apache

2.2.3. Red Hat Directory Server

2.2.4. Additional Packages

2.2.5. Firewall Configuration and iptables

2.2.6. SELinux Settings

2.3. Packages Installed on Red Hat Enterprise Linux

2.4. Required Information for Subsystem Configuration

2.5.1. Types of Hardware Tokens

2.5.1.1. Internal Tokens

2.5.1.2. External Tokens

2.5.1.3. Hardware Cryptographic Accelerators

2.5.2. Using Hardware Security Modules with Subsystems

2.5.2.1. Adding or Managing the HSM Entry for a Subsystem

2.5.2.2. Using Chrysalis LunaSA HSM

2.5.2.3. Installing External Tokens and Unsupported HSM

2.5.2.4. Setting up SELinux on nCiper netHSM 2000