Red Hat Certificate System 8.0 Install Guide
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
Apple Mac OS X 10.5.x (Leopard)
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.
14
Chapter 2. Prerequisites Before Installing Certificate System
Table 2.1. Supported Web Browsers by Platform
Platform
Red Hat Enterprise
Linux
Windows Vista
Agent Services
Firefox 3.x
Firefox 2.x
Windows XP
Mac OS 10.5.x
End User Pages
Firefox 3.x
Firefox 2.x
Internet Explorer 7 and higher
Firefox 2.x
Agent services are not supported for
Mac
Firefox 2.x
Internet Explorer 6 and higher
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
Safenet Chrysalis-ITS
LunaSA
4.5.2
nCipher netHSM 2000 2.33.60
Appliance Software
3.2.4
11.10
Client Software
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)
15
Red Hat Certificate System 8.0 Install Guide
Requester name
Additional notes (comments appended by the agent to the certificate)
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
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:
16
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 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:
17
Red Hat Certificate System 8.0 Install Guide 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." 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 Policy ."
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.
RPMs for Certificate System Subsystems and Components osutil pki-setup pki-ca pki-common pki-console pki-java-tools pki-kra pki-tps pki-migrate pki-native-tools pki-ocsp
RPMs for Tomcat Web Services ant jakarta-commons-discovery pki-tks symkey jakarta-oro
18
Chapter 2. Prerequisites Before Installing Certificate System avalon-framework avalon-logkit axis bcel classpathx-jaf classpathx-mail eclipse-ecj geronimo-specs xalan-j2 geronimo-specs-compat jakarta-commons-collections jakarta-commons-daemon jakarta-commons-dbcp jakarta-commons-digester jakarta-commons-el jakarta-commons-fileupload jakarta-commons-httpclient jakarta-commons-launcher jakarta-commons-logging jakarta-commons-modeler jakarta-commons-pool jdom jakarta-commons-beanutils ldapjdk log4j mx4j
RPMs for Apache Web Services mod_perl pcre-devel perl-XML-SAX tcl tcl-devel
RPMs for LDAP Support cyrus-sasl mozldap-devel perl-XML-NamespaceSupport perl-XML-Parser perl-Parse-RecDescent perl-XML-Simple mozldap-tools regexp tomcat5 tomcat5-common tomcat5-jasper tomcat5-server velocity werken.xpath
wsdl4j xerces-j2 xml-commons xml-commons-apis xml-commons-resolver
RPMs for SQL Lite Support for the RA perl-DBD-SQLite perl-DBI
RPMs for NSS and NSPR jss nspr nss svrcore sqlite-devel
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”
.
19
Red Hat Certificate System 8.0 Install Guide
Table 2.2. Required Information for Configuring Subsystems
Information
Login PIN
Security domain information
CA information
Subsystem information (for TPS configuration)
Directory Server hostname and port number
Directory Manager DN and password
Certificate and key recovery files (for cloning)
Description
There is a randomly-generated PIN in the
preop.pin parameter in the CS.cfg file in the instance conf/ directory. This is used to log into the configuration wizard.
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.
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.
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.
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.
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 default Directory Manager DN is cn=Directory
Manager.
If the subsystem being configured is a clone of another subsystem, then the backup files for the master subsystem must be locally accessible.
20
Chapter 2. Prerequisites Before Installing Certificate System
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.
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
21
Red Hat Certificate System 8.0 Install Guide
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
m odutil 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
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:
22
Chapter 2. Prerequisites Before Installing Certificate System 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.
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.
23
Red Hat Certificate System 8.0 Install Guide 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
m odutil manually to add the module to the secm od.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: 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
secm od.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:
24
Chapter 2. Prerequisites Before Installing Certificate System 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.
2.5.3. Viewing Tokens
To view a list of the tokens currently installed for a Certificate System instance, use the modutil utility.
1. Open the instance alias directory. For example: cd /var/lib/pki-ca/alias
2. Show the information about the installed PKCS #11 modules installed as well as information on the corresponding tokens using the modutil tool.
modutil -dbdir . -nocertdb -list
2.5.4. Detecting Tokens
To see if a token can be detected by Certificate System, use the TokenInfo utility. This is a Certificate
System tool which is available after the Certificate System packages are installed.
TokenInfo
This utility will return all tokens which can be detected by the Certificate System, not only tokens which are installed in the Certificate System.
25
