Chapter 8

Administrative Basics

---

This chapter discusses the Red Hat Certificate System (CS) user interface, the configuration file, and other basic administrative tasks like starting and stopping the server, managing logs, changing port assignments, and changing the internal database.

This chapter contains the following sections:

• The Administrative Interface
• System Passwords
• Starting, Stopping, and Restarting CS Instances
• Subsystem Configuration Overview
• Mail Server
• Configuration Files
• Logs
• Signed Audit Log
• Self Tests
• Ports
• Changing an IP Addresses
• The Internal Database
• Managing the Certificate Database
• Tokens for Storing CS Keys and Certificates
• Hardware Cryptographic Accelerators
• Configuring the Server's Security Preferences

The Administrative Interface

CS provides a GUI-based administration tool called the CS console that is accessible from Red Hat Console. Red Hat Console is a GUI-based front-end for Red Hat Administration Server and allows you to manager servers as well as users.

This section provides an overview of Red Hat Administration Server and the CS console.

Red Hat Administration Server

Red Hat Administration Server is a web-based (HTTP) server installed along with CS that enables you to configure CS through Red Hat Console. You access Administration Server by entering its URL in the Red Hat Console login screen and providing the user ID and password of the administrative user.

Administration Server must be running before you can access Red Hat Console.

For complete details about Red Hat Administration Server, see Managing Servers with Red Hat Console.

Starting Administration Server

The CS installation program automatically starts Administration Server. If you stopped Administration Server after installation, you must start it before you can administer CS from the CS console.

To start Administration Server:

1. Go to the following directory:

<server_root>

where:

<server_root>

Specifies the directory in which you installed CS.

2. Type the following command:

./start-admin

Red Hat Console

Red Hat Console is a stand-alone Java application that provides a GUI-based front end to all network resources registered in an organization's configuration directory. This unified administration interface simplifies network administration by supplying access points to all Red Hat Directory and Certificate server instances installed across a network. Similarly, it simplifies basic user and group management by providing a unified administration interface to the user directory.

You can accomplish various CS-specific tasks from the Console tab:

• Launch the CS console.
• Install instances of CS.
• Remove an instance of CS.
• Clone an instance of CS.
• Set access permissions for CS.

For complete details about Red Hat Console, see Managing Servers with Red Hat Console.

Logging Into Red Hat Console

You can launch and use Red Hat Console only when the configuration directory and Administration Server are running.

To login to Red Hat Console:

1. Go to the following directory:

<server_root>

where:

<server_root>

Specifies the directory in which you installed CS.

2. Type the following command:

./startconsole

The login dialog opens.

3. Log into Red Hat Console by filling in the following field:

User ID. Type the administrator user ID. You should login using the administrator user ID, using the cn=Directory Manager user ID allows you full privileges with Directory Server, but does not allow you to create CS server instances.

Password. Type the password for this user ID.

Administration URL. Specify the URL for the Administration Server you want to log into. This URL has the following format:

http://<machine_name>.<your_domain>.<domain>:<port_number>

For example, if your domain name is example.com and you installed Administration Server on a host machine called myHost and specified port number 12345, the URL is:
http://myHost.example.com:12345

4. Click OK.

Red Hat Console opens.

The CS Console

The CS console is a GUI-based administration interface that allows you to perform day-to-day operational and managerial duties for CS and configure the server. You launch the CS console from within Red Hat Console.

You can use the CS console to access the server locally or remotely. The console has the following tabs:

• Tasks Tab

The Tasks tab enables you to perform tasks such as starting, stopping, and restarting the server, and running the Certificate Setup Wizard. For more information, see "Starting, Stopping, and Restarting CS Instances," on page 246.

• Configuration Tab

The Configuration tab enables you to view and modify the configuration settings for the server instance. The choices available in this tab will change depending on which subsystem is installed in this server instance. The specifics of setting these configuration settings is contained in the appropriate section of this guide.

• Status Tab

The Status tab allows you to monitor the server by viewing the contents of various logs maintained by CS. See "Logs," on page 255 for more information.

Logging Into the CS Console

To log into the CS console:

1. Log into Red Hat Console, see "Logging Into Red Hat Console," on page 237.
2. Double-click the CS instance you want to open from the Red Hat Console navigation tab, or select the instance and click Open.

The CS Authenticate User dialog opens.

If this instance has not yet been setup, the Installation Wizard launches allowing you to set up this instance.

If the server is not running, you are asked to start the server first. For information on starting the server, see "Starting, Stopping, and Restarting CS Instances" on page 246.

3. You must login into CS as an administrator user of CS. Provide the administrator user ID and password in the following fields:

User ID. Provide a user ID that has CS administrator privileges.

Password. Type the password for this user ID.

Note: If SSL client authentication is set up for this server, you will be presented with a list of your certificates to choose from in order to login. You will not be presented with the userID/Password entry dialog.

4. The CS console opens.

Viewing Information About a CS instance

You can view some of the basic information about a CS instance.

To view information pertaining to a CS instance:

1. Log in to Red Hat Console (see "Logging Into Red Hat Console" on page 237).
2. In the Console tab, select the CS instance you want to view.

The right pane shows information about the selected CS instance.

The information displayed includes the following:

Server Name. A descriptive name of the CS instance.

Description. Additional information that helps you identify the CS instance. You can change this description.

Installation Date. The date the server was installed.

Server Root. The directory in which all servers are installed.

Product Name. The complete product name.

Vendor. The name of the vendor.

Version. The version number.

Build Number. The number that identifies the build that was used for this installation.

Security Level. The server's security level-whether the server is meant for use in the United States and Canada (domestic) or any other part of the world (export). See "Configuring the Server's Security Preferences" on page 309.

Server Status. The server's status-whether it is started, stopped, or unknown; normally, unknown indicates that the server hasn't been configured properly.

3. To change the name of the instance, or its description:

Select the instance and click Edit.

Details about the selected CS instance appear in the right pane. Specify the appropriate information:

Server Name. Type a name for the server.

Description. Type any additional description for the server. For example, you may want to type information that will help you identify this instance of CS.

Setting up Certificate Authentication for the CS Console

Certificate Authentication of Red Hat Console, and the CS window can now be enabled so that administrators must authenticate using a client certificate that is good for SSL authentication before logging into Red Hat Console, or the CS window. You first need to store the certificates of the administrators and then enable this feature.

Storing an Administrator's Client Certificates

You must store the certificates for any of administrator using this system. The certificate should be either from the CA itself, or from whichever CA signed the certificate for the subsystem.

Make sure the client certificate is good for SSL client authentication, otherwise, the server will not accept the client certificate and will post the following error message in the error log located in the directory <server_root>/cert-<instanceID>/logs/errors:

failure (14290): Error receiving connection (SEC_ERROR_INADEQUATE_CERT_TYPE - Certificate type not approved for application.)

Enabling SSL Client Authentication

To enable SSL client authentication in Red Hat Console:

1. Since you need to use certutil to initialize cert8.db and key3.db and to create certificate request, make sure to set the LD_LIBRARY_PATH correctly. To do this, issue the following command:

setenv LD_LIBRARY_PATH <server_root>/lib:$LD_LIBRARY_PATH

2. Use certutil in /bin/cert/tools to initialize the cert8.db and key3.db files in <home_directory>/.mcc. To do this:
   1. Go to the following directory:

<server_root>/bin/cert/tools

1. Issue the command:

./certutil -N -d <home_directory>/.mcc

3. Request the client certificate. Go to the end-entity interface for the CA that will issue the certificate and click on the Enrollment tab.
4. Select the "Manual User Dual-Use Certificate Enrollment" link.
5. Fill in all necessary information required for the form and click Submit.
6. Once you get the certificate, make sure to import it to the browser.
7. Export the certificate as p12 file.
8. Import the client certificate in p12 format to the cert8.db.

./pk12util -i <pk12file> -d "<home directory>/.mcc"

9. Log in to the CS console (see "Logging Into the CS Console" on page 239).
10. Go to the Configuration tab, and then select the Users tab in the left hand panel.
11. Click Certificates to add the client certificate.

The Manager User Certificates window appears.

12. Paste the certificate into the window.
13. Click Import.
14. Repeat from step 6 for each administrator until the certificates for all administrators have been imported.
15. Click Done.
16. Stop the CS server.
17. Go to the directory <serverRoot>/cert-<instanceID>/config
18. Open the file CS.cfg.
19. Change the value of the authType parameter from pwd to sslclientauth:

authType=sslclientauth

20. Save the file.
21. Open the file server.xml.
22. Change the clientauth="off" attribute to clientauth="on" in the SSLPARAMS section of the LS id="admin":

<LS id="admin" ip="0.0.0.0" port="8206" security="on" acceptorthreads="1" blocking="no">

<CONNECTIONGROUP id="admin_default" matchingip="default" servername="buster.mcom.com" defaultvs="admin-vs">

<SSLPARAMS servercertnickname="Server-Cert cert-buster" ssl2="off" ssl2ciphers="-rc4,-rc4export,-rc2,-rc2export,-des,-desede3" ssl3="on" ssl3tlsciphers="-fortezza,-fortezza_rc4_128_sha,+rsa_rc4_128_md5,-rsa_rc4_40_md5,+rsa_3des_sha,+rsa_des_sha,-rsa_rc2_40_md5,-fortezza_null,-fips_des_sha,+fips_3des_sha,-rsa_null_md5,-rsa_des_56_sha,-rsa_rc4_56_sha" tls="on" tlsrollback="off" clientauth="off"/>

23. Start CS.
24. Start Red Hat Console. You will be prompted for your certificate.

System Passwords

CS has a password-quality checker for internal passwords that you can configure to your needs. It stores token passwords in a plain text file, and stores all other passwords in an encrypted password cache file.

Password-Quality Checker

CS comes with a plug-in, called password-quality checker, to monitor the quality of passwords set within the CS system. All passwords used in CS are checked by the password-quality checker, which by default checks that the length of a password is at least 8 characters long; there are no checks regarding which characters are valid or invalid. If you use a password that doesn't meet the quality rules, you will get an error message.

Note that CS enforces password quality on only those passwords that it creates and manages. Passwords you enter for LDAP directory access are not subjected to quality checks. The reason for this is, the password quality is handled by the system that creates and manages the password. In an LDAP directory access, the remote directory that you authenticate to enforces the quality of the password you used because it is created and managed by the directory.

To enable you to customize the quality of passwords, the plug-in for the password-quality checker is included as a sample in the CS SDK.

Passwords Stored by the Server

CS stores passwords in two separate files. These passwords are used to bind to servers, or to unlock tokens when you start up the server.

Token Password Storage

The passwords for any tokens holding the private keys for the subsystem installed in this instance of CS are stored in the file password.conf located in the <server_root>/cert-<instance_id>/config directory. This file has read/write permission for the installer only.

This file contains the token passwords needed to open the private keys of the subsystem as follows:

• For a Certificate Manager the token password unlocks the private keys for the Certificate Manager's CA signing and SSL server certificates. If the Certificate Manager's OCSP option was enabled during installation, then the password also unlocks the private key for the Certificate Manager's OCSP signing certificate.
• For a Registration Manager the token password unlocks the private keys for the Registration Manager's signing and SSL server certificates.
• For a Data Recovery Manager the token password unlocks the private keys for the Data Recovery Manager's storage keys and transport and SSL server certificates.
• For an Online Certificate Status Manager the token password unlocks the private keys for the Online Certificate Status Manager's signing and SSL server certificates.

Deleting the password.conf File

You can choose to delete the password.conf file during CS installation, the default choice is to keep the file. You might choose to delete this file for added security of your token passwords because this file stores the passwords in a plain text file.

If you do delete the password.conf file, you must start the server instance using the command line. You will be prompted for the token passwords after entering the start-cert command. You cannot start the CS instance from the CS console. CS console does not provide the ability to enter this password when the password.conf file is absent.

Password Cache

Passwords for the internal database and other database related passwords for optional features are stored in the file pwcache.db located in the <server_root>/cert-<instance_id>/config directory. The password cache is triple-DES encrypted with a symmetric key, which is generated and stored in the cryptographic module. This file is opened using the single sign-on password, and the passwords stored are used to bind to the various services.

In order to make changes to the password cache, CS ships with a command-line named PasswordCache located in the <server_root>/bin/cert/tools directory. For complete details about this utility, see the Red Hat Certificate System Command-Line Tools Guide.

The list of passwords stored in this file includes the following:

• The bind password used by CS to access and update the internal database.
• The bind password used by CS to access and remove PINs from the authentication directory, if you've configured CS to remove PINs from the authentication directory.
• The bind password used by CS to access and create/modify user entries in the directory used for portal registration, if you've configured CS for portal enrollment.
• The bind password used by CS to access and update the LDAP directory; this is required only if you have configured CS for publishing certificates and CRLs to an LDAP-compliant directory.

Starting, Stopping, and Restarting CS Instances

Each instance of CS is started, stopped, and restarted separately. This section describes how to start, stop, and restart CS instances and how to check its current status.

Starting a Server Instance

You can start the server from either Red Hat Console or from the command line.

Starting From Red Hat Console

To start a CS instance from Red Hat Console:

1. Log in to Red Hat Console (see "Logging Into Red Hat Console" on page 237).
2. Select the CS instance you want to open from the Red Hat Console navigation tab and then right-click your mouse selecting the Start Server option from the pop-up menu.

Alternatively

1. Log in to Red Hat Console (see "Logging Into Red Hat Console" on page 237).
2. Double-click the CS instance you want to open from the Red Hat Console navigation tab, or select the instance and click Open.
3. Go to the Tasks Tab and select Start Server.

Note	If you chose to delete the password.conf file during installation, you must start the server instance on the command line; you cannot start the server instance from the CS console. For more information, see "Passwords Stored by the Server," on page 244.

Starting From the Command Line

To start a CS instance from the command line:

1. Log in either as the root user ID or with the server's user ID.
2. Go to the following directory:

<server_root>/cert-<instance_id>

3. Type the following command:

./start-cert

Note	If CS is already running, the start-up command fails. Stop the server first using the stop-cert command, then use the start-cert command.

Stopping a Server Instance

You can stop the server from either Red Hat Console or from the command line.

With this version of CS, CS is enabled for a clean shutdown. During the shutdown process, the subsystem will process any already posted requests to any of its interfaces to completion, but will accept no new requests. There is a setting in the CS.cfg file that allows you to set the absolute time out, the amount of time before the between issuing the shutdown command and actual shutdown. If this time is reached before all processes are complete, the server will shutdown without completing the processes. The default time out setting is 1 minute.

Stopping From Red Hat Console

To stop a CS instance from Red Hat Console:

1. Log in to Red Hat Console (see "Logging Into Red Hat Console" on page 237).
2. Select the CS instance you want to stop from the Red Hat Console navigation tab and then right-click your mouse selecting the Stop Server option from the pop-up menu.

Alternatively

1. Log in to Red Hat Console (see "Logging Into Red Hat Console" on page 237).
2. Double-click the CS instance you want to open from the Red Hat Console navigation tab, or select the instance and click Open.
3. Go to the Tasks Tab and select Stop Server.

Stopping From the Command Line

To stop a CS instance from the command line:

1. Log in either as root or with the server's user account.
2. Go to the following directory:

<server_root>/cert-<instance_id>

3. Type the following command:

./stop-cert

Restarting a Server Instance

You can restart the server from either Red Hat Console or from the command line.

Restarting From the CS Console

To restart a CS instance from the CS console:

1. Log in to Red Hat Console (see "Logging Into Red Hat Console" on page 237).
2. Double-click the CS instance you want to open from the Red Hat Console navigation tab, or select the instance and click Open.
3. Go to the Tasks Tab and select Restart Server.

Restarting From the Command Line

To restart a CS instance from the command line:

1. Log in either as root or with the server's user account.
2. Go to the following directory:

<server_root>/cert-<instance_id>

3. Type the following command:

./restart-cert

Subsystem Configuration Overview

Once you install CS on a host, you are ready to configure any subsystems that will run on that host. You can configure multiple subsystems on a host, or multiple instances of a single subsystem. As part of your deployment planning, you should decide which subsystems will be needed and on which hosts those subsystems will be deployed.

You can configure subsystems in any order, but you may want to plan the order to provide the smoothest setup of your deployment. For example, if you are going to be setting up a hierarchy of Certificate Managers, you should install the root CA first. You might also want to install a Certificate Manager that will develop a trusted relationship with other subsystems first.

Configuring Multiple CS Instances

When CS is installed on a host, a single instance of CS is also created and ready to be configured. You can created more instances of the server on the same machine and then set them up. For instance, you might want to add a Data Recovery Manager on the same host as a CA.

To create another instance of CS:

1. Log in to Red Hat Console (see "Logging Into Red Hat Console" on page 237).
2. In the navigation tree, select the server group in which you want to create a CS instance.
3. From the Object menu, choose Create Instance Of, then choose CS from the pop-up list.

Alternatively, you can select the server group and then right-click your mouse choosing Create Instance Of->Certificate System.

The Create Server Instance dialog opens.

4. Type a unique name or identifier for the new instance.

You can use any combination of letters (aA to zZ), digits (0 to 9), an underscore (_), and a hyphen (-); other characters and spaces are not allowed. For example, you can type Pilot_root-CA as the instance name, but not Pilot root CA.

5. Click OK.

The instance you created appears in the navigation tree.

6. To configure the instance, start the installation wizard by double-clicking the new instance in the navigation tree. See the section in this chapter on configuring the subsystem you want to setup in this instance for complete details.

Removing an Instance From a System

You can remove a CS instance from your host. Removing a CS instance is not the same as uninstalling CS. For instructions on uninstalling CS, see "Uninstalling CS" on page 76.

To remove a CS instance:

1. Log in to Red Hat Console (see "Logging Into Red Hat Console" on page 237).
2. Stop the CS instance.
3. Select the CS instance you want to remove and choose Remove Server from the Object menu.

Alternatively, you can select the CS instance you want to remove and then right-click your mouse choosing Remove Server from the pop-up menu.

4. When prompted, confirm that you want to remove the instance.

The selected CS instance is removed. The corresponding internal database is not removed. If you want to remove it, select the internal database, and repeat steps 2 through 4.

The Directory Server (configuration directory) and Administration Server binaries are also not removed; you need these to administer the remaining servers installed in the same server group.

Mail Server

The notifications and jobs features use the mail server set up in the CS instance to send its notification messages. You set up a mail server using the following procedure:

1. In the CS window, select the Configuration tab, and then in the right pane, select the SMTP tab.
2. Identify the mail server by providing the following details:

Server name. Type the fully qualified DNS host name of the machine on which your mail server is installed. The format for the host name is as follows:

<machine_name>.<your_domain>.<domain>

By default, the host name of the mail server is shown as localhost instead of the actual host name (for example, mail.example.com).

Port number. Type the port number on which the mail server is listening for requests.

3. Click Save.

Configuration Files

The runtime properties of CS are governed by a set of configuration parameters. These parameters are stored in a file that is read by the server during startup.

When you install CS, the installer creates an ASCII file, named CS.cfg, and populates it with the appropriate configuration parameters. You can control the way CS functions by making the appropriate changes in the CS console, which is the recommended method for making configuration changes. The changes you make in the CS console are reflected in the configuration file. You can also make changes directly to the configuration file, but unless specifically instructed to do so in this documentation, this is not recommended.

Locating the Configuration File

Each instance of CS has its own configuration file, CS.cfg. The file for the subsystem is different depending on your installation choices, and on which subsystem is installed in that instance.

The CS.cfg file is located in the following directory:

<server_root>/cert-<instance_id>/config

where:

<server_root>	Specifies the directory in which CS is installed
<instance_id>	Specifies the name of the CS instance

Editing the Configuration File

Caution

Do not edit the configuration file directly if you are not familiar with the configuration parameters or if you are not sure that the changes you intend to make are acceptable by the server. CS will fail to start up if you make incorrect modifications to the configuration file. Incorrect configuration can also result in data loss.

To modify the configuration file:

1. Stop the CS instance whose configuration file you want to edit (see "Starting, Stopping, and Restarting CS Instances" on page 246).

The configuration file is stored in the cache when you start CS. Any changes you make to CS through the CS console are changed in the cached version of the file. When you stop or restart the server, the configuration file stored in the cache is written to disk.

You must stop the server before editing the configuration file because your changes will be overwritten by the cached version when the server is stopped or restarted.

2. Go to the following directory:

<server_root>/cert-<instance_id>/config

3. Open the file CS.cfg in a text editor.
4. Edit the parameters in the file and save your changes.
5. Start CS (see "Starting, Stopping, and Restarting CS Instances" on page 246).

Guidelines for Editing the Configuration File

The following are guidelines for editing the configuration file:

• The format for parameters is as follows:

#comment

[parameter]=value
 

• Comment lines begin with the pound (#) character and are ignored.
• A line beginning with white space is considered a continuation of the previous line.
• Comment lines, blank lines, unknown parameters, or misspelled parameters are ignored by the server.
• Subsystem-specific parameters are distinguished by a prefix identifying the subsystem as follows:
  • ca for the Certificate Manager
  • ra for the Registration Manager
  • kra for the Data Recovery Manager
  • ocsp for the Online Certificate Status Manager
• The parameter names and their values are strings. The parameter names can be hierarchically structured with '.' notation with multiple levels-for example, ca.Policy.rule.RSAKeyRule.maxSize. The entries corresponding to a lower level (such as Policy in the example) can be requested from the configuration corresponding to its higher level (ca in the example).
• The values that need to be localized (such as distinguished names in multibyte format) should be entered in utf8 format.
• The values of some parameters are referenced to other parts of the configuration file. For example, assume that a parameter is defined as subsystem.id=ca; when this parameter is processed by the server, all the parameters beginning with ca will be used.
• The configuration file supports Unix-style file separator, the forward slash (/). If the backward slash (\) file separator is required, use two backward slashes (\\) instead of one.
• Authentication parameters:
  • All authentication-specific information, such as names of registered authentication plug-in modules and any configured instances, appears in the Authentication section of the configuration file.
  • Each registered authentication plug-in module is identified by its implementation name and the corresponding Java class.
  • Each configured instance of an authentication module is identified by the name or ID you specified when creating it.
  • You can create multiple instances from an implementation; each instance must have a unique name. To do this, you would copy all of the parameters belonging to the module used to create the instance. Change the name of each of these parameters to the new name for this instance, and then change the value of all the parameters as is appropriate for your needs.
  • The name of an authentication instance must be used in the corresponding enrollment form so that the server is able to determine the authentication method during end-user enrollment.
• Job Scheduler parameters:
  • All job-specific information, such as registered job modules and configured instances, appears in the Job Scheduler section of the configuration file.
  • Each registered job module is identified by its implementation name and the corresponding Java class.
  • Each job (or configured instance of a job module) is identified by the name specified when the job was created.
  • You can create as many instances of an implementation as you like; each instance must have a unique name. To do this, you would copy all of the parameters belonging to the module used to create the instance. Change the name of each of these parameters to the new name for this instance, and then change the value of all the parameters as is appropriate for your needs.
• Policy parameters:
  • All policy-specific information, such as registered policy plug-in implementations, configured rules, and ordering, appear in the Policy section of the configuration file.
  • Each registered policy plug-in module is identified by its implementation name and the corresponding Java class.
  • Each configured rule of a policy module is identified by the name specified when the rule was created.
  • You can create multiple rules out of an implementation; each rule must have a unique name. To do this, you would copy all of the parameters belonging to the module used to create the instance. Change the name of each of these parameters to the new name for this instance, and then change the value of all the parameters as is appropriate for your needs.

Duplicating Configuration From One Instance to Another

If you have deployed a large number of CS instances that are identical-for example, multiple Registration Managers-and you want all these instances to have the same configuration, you can accomplish this by configuring one of the instances and then replacing the configuration files of the other instances with the one that contains the required configuration.

Note	Be careful when replacing configuration of one instance with another. The configuration file for an instance contains instance-specific parameters. If you replace these parameters, the instance will fail to start or function properly.

Logs

This section explains how to use the CS console to configure logs maintained by CS, and how to monitor the server's activities by viewing log contents.

This section contains the following sub-sections:

• About Logs
• Configuring Logs in the CS Console
• Monitoring Logs
• Signing Log Files
• Registering a Log Module
• Deleting a Log Module

About Logs

CS creates log files that record events related to its activities, such as administration, communications using any of the protocols the server supports, and various other processes employed by the subsystems the server manages. While CS is running, it keeps a log of information and error messages on all the components it manages.

Log plug-in modules are listeners, which are implemented as Java classes and are registered in the CS policy framework.

Each instance of Red Hat Certificate System (CS) maintains its own log files.

All the log files and rotated log files, except for audit logs (signed or not), are located in the following directory:

<server_root>/cert-<instance_id>/logs

Audit logs, signed or not, are located in the following directory:

<server_root>/cert-<instance_id>/logs/signedAudit

You can change the default location for logs by modifying it in the configuration.

Error and Access Logs

The error and access logs are created by Red Hat Enterprise Server, which is installed with CS providing HTTP services. The error log contains the HTTP error messages the server has encountered. The access log lists access activity through the HTTP interface. These logs are not available or configurable from within CS; they are only configurable from within Enterprise Server. See the Red Hat Enterprise Server documentation for information about configuring these logs.

Self-Tests Log

The self-tests log records information obtained during the self-tests run when the server starts up, or when the self-tests are manually run (on demand). The tests can be viewed by opening this log. This log is not configurable through the CS Console, you must configure it by changing settings in the CS.cfg file. The information about logs in this section does not pertain to this log. See "Self Tests," on page 272 for more information about self-tests.

Installation and Setup Logs

The following logs are created when the CS instance is installed, the information about logs in this section does not pertain to these logs:

config_cgi.log. Created by config_cgi cgi that forwards configuration daemon client (Java UI) requests to the configuration daemon.

daemon.err. Created by the start_daemon cgi, captures the standard error of the start_daemon cgi

daemon.out. Created by the start_daemon cgi, captures the standard output of the start_daemon cgi

start_daemon.log. Created by the start_daemon cgi that starts the configuration daemon, logs errors of the daemon startup

service.log. created by ntservice.exe that registers CS as a NT service (Windows specific file).

wizard.log. Created by the Installation wizard that installs and configures the subsystems. Logs errors during this installation and configuration.

System Log

This log records information about requests to the server (all HTTP and HTTPS requests) and the responses from the server. Information recorded in this log includes the IP address of the client machine that accessed the server, operations performed (for example, search, add, edit), and the result of the access (for example, the number of entries returned). This log is on by default.

Transactions Log

This log records messages specific to the certificate service-messages such as certificate requests, certificate renewal and revocation requests, and CRL publication-and enables you to detect any unauthorized access or activity. This log is on by default.

Signed Audit Log

This log contains audit records for events that have been set up as recordable events. If the logSigning attribute is set to true, the audit log is signed with a log signing certificate belonging to the server. This certificate can be used by auditors to verify that the log has not been tampered with. See "Signed Audit Log," on page 268.

Services That Are Logged

All major components and protocols (or services) of CS log messages to log files. Table 8-1 lists services that are logged by default. If you want to view messages logged by a specific service, you can customize log settings accordingly. For details, see "Monitoring Logs" on page 265.

Table 8-1 Services Logged  

Service	Description
ACLs	Specifies logged events related to access control lists.
Administration	Specifies logged events related to this server's administration activities-that is, HTTPS communication between the CS console and CS.
All	Specifies logged events related to all the services.
Authentication	Specifies logged events related to this server's activity with the authentication module.
Certificate Authority	Specifies logged events related to the Certificate Manager.
Database	Specifies logged events related to this server's activity with the internal database.
HTTP	Specifies logged events related to the HTTP activity of the server. (Note, HTTP events are actually logged to the errors log belonging to the Red Hat Enterprise Server that is incorporated into CS to provide HTTP services.)
Key Recovery Authority	Specifies logged events related to the Data Recovery Manager.
LDAP	Specifies logged events related to this server's activity with the LDAP directory (used for publishing certificates and CRLs).
OCSP	Specifies logged events related to OCSP.
Others	Specifies logged events related to other activities of this server, such as command-line utilities and other processes.
Registration Authority	Specifies logged events related to the Registration Manager.
Request Queue	Specifies logged events related to the request queue activity of this server.
User and Group	Specifies logged events related to users and groups managed by this server.

Log Levels (Message Categories)

For identification and filtering purposes, events logged by all CS-supported services are classified into various categories. These are listed in Table 8-2. Each category represents messages that are of the same or a similar nature or that belong to a specific functional area.

In the CS configuration, each message category corresponds to a specific log level. Log levels are represented by numbers (digits) 1 to 6, each digit indicating the level of logging to be performed by the server-that is, how detailed the logging should be.

• A higher priority level (a larger digit) means less detail because only events of high priority are logged.
• A lower priority level (a smaller digit) means greater detail because more kinds of events are recorded in the log file.

Table 8-2 Classification of Log Entries or Messages  

Log level	Message category	Description
0	Debugging	These messages contain debugging information. Generally, you would not want to set a log to the debugging level since it would yield far too much information for normal use.
1	Informational (default selection for audit log)	These messages provide general information about the state of CS. For example, status messages such as "Certificate System initialization complete" and "Request for operation succeeded" fall into this category.
2	Warning	These messages are warnings only and do not indicate any failure in the normal operation of the server.
3	Failure (default selection for system and error logs)	These messages indicate errors and failures that prevent the server from operating normally. Examples of messages that fall into this category include failures to perform a certificate service operation ("User authentication failed" or "Certificate revoked") and unexpected situations that can cause irrevocable errors ("The server cannot send back the request it processed for a client through the same channel the request came from the client").
4	Misconfiguration	These messages indicate that a misconfiguration in the server is causing an error.
5	Catastrophic failure	These messages indicate that because of an error, the service cannot continue running.
6	Security-related events	These messages identify occurrences that affect the security of the server (for example, "Privileged access attempted by user with revoked or unlisted certificate").

You can use log levels to filter log entries based on the severity of an event. By default, a level 3 (Failure) is set for all services.

The log level is additive-that is, specifying a value of 3 causes levels 4, 5, and 6 to be logged. Log data can be voluminous, especially at lower (more verbose) logging levels. Make sure that the host machine has sufficient disk space for all the log files. It is also important to define your logging level, log rotation, and server-backup policies appropriately so that all the log files are backed up and the host system doesn't get overloaded; otherwise, you may lose information.

Buffered Versus Unbuffered Logging

CS supports buffered logging for all types of logs. You can choose to configure the server for either buffered or unbuffered logging.

If you configure for buffered logging, the server creates buffers for the corresponding logs, and it holds the messages in these buffers for as long as possible. The server flushes out the messages to the log files only when either of the following conditions occurs:

• The buffer gets full-the buffer gets full when the buffer size is equal to or greater than the value specified by the bufferSize configuration parameter. The default value for this parameter is 512 KB.
• The flush interval for the buffer is reached-the flush interval is reached when the time interval since the last buffer flush is equal to or greater than the value specified by the flushInterval configuration parameter. The default value for this parameter is 5 seconds.
• When current logs are read from CS console-the server retrieves the latest log when it is queried for current logs.

If you configure the server for unbuffered logging, the server flushes out messages as they are generated to the log files. Because the server performs an I/O operation (writing to the log file) each time a message is generated, configuring the server for unbuffered logging decreases performance.

Log File Rotation

Log files are rotated when either of the following occur:

• The size limit for the corresponding file is reached-the size of the corresponding log file is equal to or greater than the value specified by the maxFileSize configuration parameter. The default value for this parameter is 100 KB.
• The age limit for the corresponding file is reached-the corresponding log file is equal to or older than the interval specified by the rolloverInterval configuration parameter. The default value for this parameter is 2592000 seconds (every hour).

When a log file is rotated, the old file is named using the name of the file with an appended time stamp. The appended time stamp is an integer that indicates the date and time the corresponding active log file was rotated. The date and time have the forms YYYYMMDD (Year, Month, Day) and HHmmSS (Hour, Minute, Second), in that order.

Log files, especially the audit log file, contain critical information. So it is good practice to periodically archive rotated log files to some archive media. You can archive log files by copying the entire log directory to your archive media.

CS does not provide any tool or utility for archiving log files. Use the tools or utilities that your operating system provides for archiving.

CS does, however, provide a command-line utility, called signtool, that allows you to sign log files before archiving them. This gives you a means of tamper detection. For details, see "Signing Log Files" on page 266.

Note that signing log files is an alternative to the signed audit logs feature. Signed audit logs allows you to create audit logs that are automatically signed, whereas this process describes how to manually sign archived logs. See "Signed Audit Log," on page 257 for details about signed audit logs.

By default, rotated log files are not deleted.

Configuring Logs in the CS Console

This procedure describes how to configure system, transaction, and audit logs.

To configure logs for a CS instance:

1. Log in to the CS console (see "Logging Into the CS Console" on page 239).
2. In the navigation tree, select Logs.

On the right pane, the Log Event Listener Management tab appears. It lists the currently configured listeners.

3. Either create a new log instance, delete an existing instance, or modify an existing instance:

To create a new log instance:

1. Click Add in the Log Event Listener Management tab.

The Select Log Event Listener Plug-in Implementation window appears. It lists registered log modules.

1. Select a plug-in module.
2. Click Next.

The Log Event Listener Editor window opens.

1. Continue to step 4.

To delete a log instance:

1. Select a listener that you want to delete in the Log Event Listener list.
2. Click Delete
3. Skip to step 5.

To modify an existing log instance:

1. Select a listener that you want to modify in the Log Event Listener list.
2. Click Edit/View.

The Log Event Listener Editor window opens.

1. Continue to step 4.
4. Make changes to the following fields in the Log Event Listener Editor window:

Log Event Listener ID. Type a unique name that will help you identify the listener; be sure to note the following:

• Use any combination of letters (aA to zZ), digits (0 to 9), an underscore (_), and a hyphen (-);
• Do not use other characters or spaces.

type. Select transaction to create a listener that records audit logs. For error and system logs, select system.

enabled. Select to enable; deselect to disable. Only enabled logs actually record events.

level. From the drop-down list, select a log level. The choices are Debug, Information, Warning, Failure, Misconfiguration, Catastrophe, and Security. The default selection is Failure. For more information, see "Log Levels (Message Categories)" on page 258.

fileName. Type the full path, including the filename, to the file to write messages. (Make sure that the server has read/write permission to the file.)

bufferSize. Type the buffer size in kilobytes (KB) for the log. The default size is 512 KB. For more information, see "Buffered Versus Unbuffered Logging" on page 259. Once the buffer reaches this size, the contents of the buffer are flushed out and copied to the log file.

flushInterval. Type the interval, in seconds, to flush the buffer to the file. The default interval is 5 seconds. The flushInterval is the amount of time before the contents of the buffer are flushed out and added to the log file.

maxFileSize. Type the file size in kilobytes (KB) for the error log. The default size is 100 KB. The maxFileSize determines how large a log file can become before it is rotated. Once it reaches this size, the file is copied to a rotated file, and the log file is started anew. For more information, see "Log File Rotation" on page 260.

rolloverInterval. From the drop-down list, select the frequency at which the server should rotate the active error log file. The available choices are Hourly, Daily, Weekly, Monthly, and Yearly. The default selection is Monthly. For more information, see "Log File Rotation" on page 260.

expirationTime. Type, in seconds, the age limit for deleting the rotated log files. The default value is 0 seconds, which indicates that the rotated log files should not be deleted. If you provide a value, the rotated log will be deleted from your system after that time has elapsed. This is no longer supported. Logs will not be deleted, you cannot set a time for the automatic deletion of logs.

The signed audit log has these additional settings:

logSigning. Set to true to enable signed logging; set to false to disable signed logging. When you enable this parameter, you must also provide a value for the signedAuditCertNickname parameter. When this feature is enabled, this log can only be viewed by an auditor. See "Signed Audit Log," on page 257 for more information about signed audit logs.

signedAuditCertNickname. The nickname of the certificate used to sign audit logs. The private key for this certificate must be accessible to the subsystem in order for it to sign the log.

events. Specifies which events will be logged to the audit log. Lists each event separated by a comma with no spaces. You can remove events from the list. See Table 8-3 on page 269 for a complete list of auditable logging events.

5. Click OK.

You are returned to the Log Event Listener Management tab.

6. Click Refresh.

Configuring Logs in the CS.cfg File

To modify the configuration settings for logs:

1. Stop the CS instance.
2. Open the CS.cfg file located in the directory <server_root>/cert-<instance>/config
3. To create a new log, you copy all of the entries for either the system or transactions log. These are the parameters that begin with log.instance.Transactions or log.instance.System. Paste all entries at the bottom of the logging section and change the name of this instance by changing the word "Transactions" or "System" in each parameter to the new name.
4. To configure a log instance, modify the parameters associated with that log. These parameters begin with log.instance and include the following parameters:

bufferSize. Specify the buffer size in kilobytes (KB) for the log. The default size is 512 KB. For more information, see "Buffered Versus Unbuffered Logging" on page 259. Once the buffer reaches this size, the contents of the buffer are flushed out and copied to the log file.

enable. Specify true to enable; false to disable. Only enabled logs actually record events.

expirationTime. Specify, in seconds, the age limit for deleting the rotated log files. The default value is 0 seconds, which indicates that the rotated log files should not be deleted. If you provide a value, the rotated log will be deleted from your system after that time has elapsed. This is no longer supported. Logs will not be deleted, you cannot set a time for the automatic deletion of logs.

fileName. Specify the full path, including the filename, to the file to write messages. (Make sure that the server has read/write permission to the file.)

flushInterval. Specify the interval, in seconds, to flush the buffer to the file. The default interval is 5 seconds. The flushInterval is the amount of time before the contents of the buffer are flushed out and added to the log file.

level. Specify a log level. The choices are 0 for Debug, 1 for Information, 2 for Warning, 3 for Failure, 4 for Misconfiguration, 5 for Catastrophe, and 6 for Security. The default selection is 1. For more information, see "Log Levels (Message Categories)" on page 258.

maxFileSize. Specify the file size in kilobytes (KB) for the error log. The default size is 100 KB. The maxFileSize determines how large a log file can become before it is rotated. Once it reaches this size, the file is copied to a rotated file, and the log file is started anew. For more information, see "Log File Rotation" on page 260.

register. If this variable is set to false (the default value), the self tests messages will only be logged to the log file specified by selftests.container.logger.fileName. If this variable is set to true, then the self tests messages will be written to BOTH the log file specified by selftests.container.logger.fileName as well as to the log file specified by log.instance.Transactions.fileName.

rolloverInterval. Specify the frequency at which the server should rotate the active error log file. The available choices are Hourly, Daily, Weekly, Monthly, and Yearly. The default selection is Monthly. For more information, see "Log File Rotation" on page 260.

type. Set to transaction or system.

5. Save the file.
6. Start the CS instance.

Monitoring Logs

When you have problems with CS that require troubleshooting, you may find it helpful to check the error or informational messages that the server has logged. Also, by examining the log files you can monitor many aspects of the server's operation. You can view certain log files in the CS console. You can also view log files by opening them in the file system. See "About Logs," on page 255 for information on the location of logs and the log files available.

To view the contents of an active or rotated system log file:

1. Log in to the CS console (see "Logging Into the CS Console" on page 239).
2. Select the Status tab.
3. In the navigation tree, under Logs, select the log you want to view.
4. In the Display Options section, specify your viewing preferences:

Entries. Type the maximum number of entries to be displayed. When this limit is reached, CS returns any entries it has located that match the search request. If you enter zero (0), no messages are returned. If you leave the field blank, the server returns every matching entry (no limit) regardless of the number found.

Source. Select the CS component (or service) for which log messages are to be displayed from the drop-down list.If you choose All, messages logged by all components that log to this file are displayed. For more information, see "Services That Are Logged" on page 257.

Level. Select a message category that represents the log level for filtering messages. For more information on log levels, see "Log Levels (Message Categories)" on page 258.

Filename. Select the log file you want to view. Choose Current to view the currently active system log file.

5. Click Refresh.

The table displays the system log entries. The entries are in reverse chronological order, with the most current entry placed at the top. Use the scroll arrows on the right edge of the panel to scroll through the log entries.

For each entry you see the following details:

Source. Indicates the CS component or resource that logged the message.

Level. Indicates the severity of the corresponding entry, see Table 8-2 on page 258 for more information.

Date. Indicates the date on which the entry was logged.

Time. Indicates the time at which the entry was logged.

Details. Provides a brief description of the log.

6. To view an entry in its entirety, either double-click it or select the entry and click View.

Signing Log Files

CS allows you to digitally sign log files before you archive them or distribute them for audit purposes. This feature enables you to check whether the log files have been tampered with since being signed.

Note that this is an alternative to the signed audit logs feature. Signed audit logs allows you to create audit logs that are automatically signed, whereas this process describes how to manually sign archived logs. See "Signed Audit Log," on page 257 for details about signed audit logs.

For signing log files, you use a command-line utility called Red Hat Signing Tool (signtool). For details about this utility, check this site: http://www.mozilla.org/projects/security/pki/nss/tools/

The utility uses information in the certificate, key, and security module databases of CS.

When you are ready with all this information, follow the procedure below to sign the log directories:

1. Go to the CS instance in which the CA whose key pair you want to use for signing is installed.
2. Type the following command with the appropriate information:

signtool -d <secdb_dir> -k <cert_nickname> -Z <output> <input>

where:

<secdb_dir>	Specifies the path to the directory that contains the certificate, key, and security module databases for the CA. This must be the same path you used to copy the security module database in step 2. If you are using the default CS location, the value would be <server_root>/alias.
<cert_nickname>	Specifies the nickname of the certificate you want the utility to use for signing.
<output>	Specifies the name of the JAR file (a signed zip file).
<input>	Specifies the path to the directory that contains the log files.

Registering a Log Module

You can create new log modules using the CS SDK. If you do create a log module, you need to register it before it is available for use.

You can register new log plug-in modules using the CS console. Registering a new module involves specifying the name of the module and the full name of the Java class that implements the log interface.

Before registering a plug-in module, be sure to put the Java class for the module in the classes directory (the implementation must be on the class path).

To register a log plug-in module with a CS instance:

1. Log in to the CS console (see "Logging Into the CS Console" on page 239).
2. Select the Configuration tab.
3. In the navigation tree, select Logs, and then in the right pane, select the Log Event Listener Plug-in Registration tab.
4. Click Register.

The Register Log Event Listener Plug-in Implementation window appears.

5. Specify information as appropriate:

Plugin name. Type a name for the plug-in module.

Class name. Type the full name of the class for this module-that is, the path to the implementing Java class. If this class is part of a package, be sure to include the package name. For example, if you are registering a class named customLog and if this class is in a package named com.customplugins, type com.customplugins.customLog.

6. Click OK.

You are returned to the Log Event Listener Plug-in Registration tab.

7. To view the updated configuration, click Refresh.

Deleting a Log Module

You can delete unwanted log plug-in modules using the CS console. Before deleting a module, be sure to delete all the listeners that are based on this module; see "Log File Rotation" on page 260.

To delete a module:

1. Log in to the CS console (see "Logging Into the CS Console" on page 239).
2. Select the Configuration tab.
3. In the navigation tree, select Logs, and then in the right pane, select the Log Event Listener Plug-in Registration tab.
4. In the Plug-in Name list, select the module you want to delete and click Delete.
5. When prompted, confirm the delete action.

Signed Audit Log

The signed audit log is a feature that creates a log recording system events; the events that are recorded are selectable from a list of events. This feature, when enabled, records all system events and produces a verbose set of messages about this activity; be careful when using this feature to provide enough space in your file system for this log. The signed audit log feature is disabled by default.

You can also set this audit log up as a signed audit log. You enable this by setting the logSigning parameter to enable and providing the nickname of the certificate that will be used to sign this log.

When this log is setup as a signed audit log, only a user with auditor privileges can access and view the log. Auditors can use the AuditVerify tool to verify that signed audit logs have not been tampered with.

When you first set the server up, if you have not created a dedicated certificate for log signing, but you want to turn on the auditing feature anyway, you can use the singing certificate for that subsystem to sign the logs. To do this, specify caSigningCert cert-<CS instance name> as the value in the signedAuditCertNickname parameter for a Certificate Manager, specify the appropriate signing certificate for other subsystems.

You can also configure which events are recorded in the log by adding or deleting the event type form the value of the events parameter. Table 8-3 lists the events that are loggable events. To add an event, add the logging event to the list; to delete an event, remove it from the list. Log events are separated by commas with no spaces.

Table 8-3 Signed-Audit Log Events

Logging Event	Type of Log Messages are Generated
AUDIT_LOG_STARTUP	The startup of the subsystem, and thus the start of the startup of the audit function.
AUDIT_LOG_SHUTDOWN	The shutdown of the subsystem, and thus the start of the startup of the audit function.
ROLE_ASSUME	A user assuming a role. A user assumes a role once they have passed through authentication and authorization systems. Note that only the default roles of administrator, auditor, and agent will be tracked. Custom roles are not tracked.
CONFIG_CERT_POLICY	A change is made to the configuration settings for the policy framework.
CONFIG_CERT_PROFILE	A change is made to the configuration settings for the certificate profile framework.
CONFIG_CRL_PROFILE	A change is made to the configuration settings for the CRL framework, in other words, any of the settings for CRLs including extensions, frequency, and CRL format.
CONFIG_OCSP_PROFILE	A change is made to the configuration settings for the Online Certificate Status Manager.
CONFIG_AUTH	A change is made to the configuration settings for the authentication framework.
CONFIG_ROLE	A change is made to the configuration settings for roles including changes made to users or groups.
CONFIG_ACL	A change is made to the configuration settings for the ACL framework.
CONFIG_SIGNED_AUDIT	A change is made to the configuration settings for the signed audit feature.
CONFIG_ENCRYPTION	A change is made to the encryption settings including certificate settings and SSL cipher preferences.
CONFIG_TRUSTED_PUBLIC_KEY	The certificate setup wizard is used to import certificates into the certificate database, or any activity in "Manage Certificates."
CONFIG_DRM	The configuration associated with a DRM changes.
SELFTESTS_EXECUTION	The self-tests are executed.
AUDIT_LOG_DELETE	The signed audit log expires or is deleted. Note: The authorization system should not allow such a deletion.
LOG_PATH_CHANGE	The path or name for the signed audit, system, transaction or any customized log is changed. Note: The authorization system should not allow such a change.
LOG_EXPIRATION_CHANGE	When an attempt is made to change log expiration time. Note: The authorization system should not allow such a change.
PRIVATE_KEY_ARCHIVE	When an encryption private key is requested during enrollment.
PRIVATE_KEY_ARCHIVE_PROCESSED	A private encryption key is archived in the Data Recovery Manager (the private key request is processed).
KEY_RECOVERY_REQUEST	A request is made to recover a private encryption key that is stored in the Data Recovery Manager.
KEY_RECOVERY_AGENT_LOGIN	DRM agents log in as recovery agents to approve key recovery requests.
KEY_RECOVERY_PROCESSED	A key recovery has been processed.
KEY_GEN_ASYMMETRIC	Asymmetric keys are generated
NON_PROFILE_CERT_REQUEST	A certificate request is made that is not through the certificate profile framework.
PROFILE_CERT_REQUEST	A certificate request is made through the certificate profile framework.
CERT_REQUEST_PROCESSED	A certificate request is being processed.
CERT_STATUS_CHANGE_REQUEST	The request is made to change the status of a certificate.
CERT_STATUS_CHANGE_REQUEST_PROCESSED	A certificate status change is processed.
AUTHZ_SUCCESS	A CS user is successfully processed by the authorization servlets.
AUTHZ_FAIL	A CS user is not successfully processed by the authorization servlets.
INTER_BOUNDARY	Records stat transfer between different subsystems.
AUTH_FAIL	A CS user does not successfully authenticate.
AUTH_SUCCESS	A CS user does successfully authenticate.
CERT_PROFILE_APPROVAL	A certificate profile sent by an administrator is approved by an agent.
PROOF_OF_POSSESSION	When proof of possession is checked during certificate enrollment.
CRL_RETRIEVAL	When a CRL is retrieved by the OCSP Responder
CRL_VALIDATION	When a CRL is retrieved and validation process occurs.
CMC_SIGNED_REQUEST_SIG_VERIFY	Used when CMC (agent-pre-signed) cert requests or revocation requests are submitted and signature is verified.
AUDIT_LOG_SIGNING	The audit buffer is signed and flushed to disk.

Setting Up Signed Audit Logs

To set up signed audit logs:

1. Set up the certificate profiles caAuditCert and raAuditCert. See "Setting Up Certificate Profiles," on page 414 for information about setting up certificate profiles. See Chapter 11, "Certificate Profiles" for general information about certificate profiles.
2. Approve the caAuditCert and raAuditCert certificate profiles by approving them in the agent services interface, thus enabling them.

If the request for this certificate is received in the end-entity interface of a Certificate Manager, enable the caAuditCert profile in that Certificate Manager.

If the request for this certificate is received in the end-entity interface of a Registration Manager, enable the raAuditCert profile in that Registration Manager and enable the raAuditCert profile in that Certified Manager that processes the requests of that Registration Manager.

3. Use the Certificate Setup Wizard to obtain a certificate request for the private keys and certificates that will be used to sign the log files. When running the certificate wizard, specify that the request is of type Other, and request that the output be a certificate request in PKCS#10 format. See "Certificate Setup Wizard," on page 289 for information about using the Certificate Setup Wizard to generate requests.
4. Submit the PKCS#10 request generated in the previous step to the profile enrollment for auditor certificates in the end-entity interface of the Certificate Manager that will issue the certificate.
5. Set up the signed audit log-it is disabled by default-by setting it up in Red Hat Console. Follow the procedure in the section "Configuring Logs in the CS Console," on page 261. Specify the nickname of the log you received in the previous step as the value of the signedAuditCertNickname parameter and specify the events that will be logged in the events parameter.
6. Assign auditor users, if you have not done so, by creating the user and assigning them to the auditor group. Members of the auditor group are the only users who can view and verify the signed audit log. See "Setting up Administrators, Agents, and Auditors," on page 318 for details about setting up auditors.
7. Auditors can view signed audit logs by viewing them from the IT environment.
8. Auditors can verify logs by using the AuditVerify tool. See the CS Command-Line Tools Guide for details about using this tool.

Audit Logging Failures

There are events that could cause the audit logging function to fail. In other words, events cannot be written to the log. For example, when the file system containing the audit log file is full or when the file permissions for the log file is accidentally changed. If audit logging fails, CS will shut down in the following manner:

• Servlets are disabled and will not processes new requests.
• All pending and new requests are killed.
• The CS subsystem is shut down.

When this happens, CS administrator(s) and CS auditor(s) should work together with the Operating System administrator to resolve the disk space or file permission issue(s). When the IT problem is resolved, the auditor should make sure that the last audit log entries are signed. If not, they should be preserved by manual signing (see "Signing Log Files" on page 266), archived, and removed to prevent audit verification failures in the future. When all is well, the CS administrator(s) can then restart CS.

Self Tests

CS has added functionality to allow for self tests of the server. The current implementation contains a small set of self-tests, created as plug-ins. You can expand the number of self tests by creating new self test plug-ins using the CS SDK.

The self-tests are run at start up and can also be run on demand. The start up self tests run when the server starts up, and will keep the server from starting up if a critical self-test fails. The on-demand self tests are run by clicking the self tests button in a new CS window interface page.

To run an on-demand self test:

1. Log in to the CS console (see "Logging Into the CS Console" on page 239).
2. Select Red Hat Certificate System at the top of the left pane.
3. Select the Self Tests tab.
4. Click Run.

The self-tests that are configured for this subsystem will run. If any critical self-tests fail, the server will stop.

The On-Demand Self Tests Results window appears showing the logged events for this run of the self-tests.

Self Test Logging

A new log, selftest.log, has been added to the log directory which contains reports for both the start up self tests and the on-demand self tests. You can configure this log by changing the setting for the log in the CS.cfg file. See "Modifying Self Test Configuration," on page 274 for details.

Self Test Configuration

The self tests feature, and individual self tests, are registered and configured in the CS.cfg file. Self tests can either be "enable" or "disable", meaning that a particular self test is listed for either on-demand or start up self test, and it can have two states, "nothing" or "critical."

Critical self tests have a semi-colon and the word "critical" after the name of the self-test. Otherwise, nothing is in this place. The server will shut down when a critical self test fails during on demand self tests; the server will not start when a critical self test fails during start up.

The currently implemented self-tests are automatically registered and configured when you install a CS instance. The self tests that are registered and configured are those associated with which type of subsystem has been configured with this server instance.

You turn the self test off, or change which self tests are considered critical by changing those setting in the CS.cfg file. To turn a self test off, you remove from the list of self tests that run either on-demand or at start up.

Modifying Self Test Configuration

To modify the configuration settings for self tests:

1. Stop the CS instance.
2. Open the CS.cfg file located in the directory <server_root>/CS-<instance>/config
3. To edit the settings for the self test log, edit the entries that begin with selftests.container.logger. These include the following parameters:

bufferSize. Specify the buffer size in kilobytes (KB) for the log. The default size is 512 KB. For more information, see "Buffered Versus Unbuffered Logging" on page 259. Once the buffer reaches this size, the contents of the buffer are flushed out and copied to the log file.

enable. Specify true to enable; false to disable. Only enabled logs actually record events.

expirationTime. Specify, in seconds, the age limit for deleting the rotated log files. The default value is 0 seconds, which indicates that the rotated log files should not be deleted. If you provide a value, the rotated log will be deleted from your system after that time has elapsed. For more information, see "Log File Rotation" on page 260. This is no longer supported. Logs will not be deleted, you cannot set a time for the automatic deletion of logs.

fileName. Specify the full path, including the filename, to the file to write messages. (Make sure that the server has read/write permission to the file.)

flushInterval. Specify the interval, in seconds, to flush the buffer to the file. The default interval is 5 seconds. The flushInterval is the amount of time before the contents of the buffer are flushed out and added to the log file.

level. The default selection is 1, this log is not set up for any level beside 1.

maxFileSize. Specify the file size in kilobytes (KB) for the error log. The default size is 100 KB. The maxFileSize determines how large a log file can become before it is rotated. Once it reaches this size, the file is copied to a rotated file, and the log file is started anew. For more information, see "Log File Rotation" on page 260.

register. If this variable is set to false (the default value), the self tests messages will only be logged to the log file specified by selftests.container.logger.fileName. If this variable is set to true, then the self tests messages will be written to BOTH the log file specified by selftests.container.logger.fileName as well as to the log file specified by log.instance.Transactions.fileName.

rolloverInterval. Specify the frequency at which the server should rotate the active error log file. The available choices are Hourly, Daily, Weekly, Monthly, and Yearly. The default selection is Monthly. For more information, see "Log File Rotation" on page 260.

type. Set to transaction, don't change this.

4. To edit the order in which the self test are run, specify the order by listing any of the self test as the value of the following parameters separated by a comma and a space.

To mark a self test critical, add a colon and the word critical to the name of the self test in the list.

To disable a self test, remove it as the value of either parameter.

selftests.container.order.onDemand

selftests.container.order.startup

5. Save the file.
6. Start CS.

Ports

About Ports

CS listens on different ports for requests from different types of users. As illustrated in Figure 8-1, it listens on an administration port, an agent port, and an end-entity port.

Figure 8-1 CS Ports

Port Considerations

When choosing ports for CS consider the following:

• Be sure to choose ports that are unique on the host system.
• To verify that a port is available for use, check the appropriate file for your operating system; port numbers for network-accessible services are usually maintained in a file named services.
• On Unix, if you are not running as root or superuser when you install or start the server, you will have to use a port number higher than 1024.

Administration Port

The administration port is an SSL (encrypted) port on which CS listens to requests from its administration interface, the CS console. When you install CS, a random number (greater than 1024) is assigned to the administration port. You can change this port number at any time, to any number between 1 and 65535.

Agent Port

The agent port is an SSL (encrypted) port on which CS listens to requests from agents; agents make these requests from the appropriate Agent Services interface.

• The Certificate Manager and Registration Manager agents use the agent port to process certificate issuance and management requests from end entities and to perform certain other privileged operations over HTTPS.
• Data Recovery Manager agents use the agent port for recovering end users' encryption private keys over HTTPS.

Agent functions always require SSL client authentication.

When you install CS, it assigns a random number (greater than 1024) as the agent port number and prompts you to change it, if necessary; the port number can be any number between 1 and 65535. The number you choose for the agent port affects your agent users-all agents access CS by specifying the name of the server (the CS instance) and the agent port number in the URL. For example, if you choose port number 4430, the URL would look like this:

https://<hostname>:4430/<subsystem>

<hostname> is in the form <machine_name>.<your_domain>.<domain>

<subsystem> is a prefix identifying the subsystem that hosts the agent interface: ca for the Certificate Manager, ra for the Registration Manager, kra for the Data Recovery Manager, and ocsp for Online Certificate Status Manager.

For example, the URL to a Certificate Manager agent interface would look like this: https://demoCA.example.com:5600/ca

If you change the agent port number, be sure to inform your agent users.

End-Entity Ports

For requests from end entities, CS can listen to two ports, an SSL (encrypted) port and a non-SSL port. End entities make these requests from the end entity services interface.

CS provides the following services through the HTTP and HTTPS ports:

• The HTTP port can be used to service end-entity-initiated PKI requests, such as enrollment, renewal, and revocation; enrollment requests can include requests from Cisco routers (using the CEP protocol); general certificate retrieval requests, such as retrieving a single certificate identified by a serial number, listing certificates based on certain criteria (for example, an LDAP search filter defined over standard attributes), and getting a CA's certificate chain. You can disable this port if it will not be used.
• The HTTPS port can be used to service end-entity-initiated PKI requests, such as enrollment, renewal, and revocation; enrollment requests can include requests from Cisco routers (using the CEP protocol); general certificate retrieval requests, such as retrieving a single certificate identified by a serial number, listing certificates based on certain criteria (for example, an LDAP search filter defined over standard attributes), and getting a CA's certificate chain. The HTTPS port uses SSL authentication providing a secure transfer of data to this port.

Similar to the HTTP port, you can enable or disable the HTTPS port. For example, if you don't want end-entity interaction with a Certificate Manager, you can disable the HTTPS port. For details, see "Changing a Port Number" on page 278.

If this CS instance is for a Certificate Manager and if the Certificate Manager is configured to service OCSP requests from OCSP-compliant clients, then this port must be enabled so that OCSP-compliant clients can successfully query the Certificate Manager for the revocation status of a certificate. For details, see "Setting Up a Certificate Manager with OCSP Service" on page 161.

Similarly, for issuing certificates to routers (using the CEP protocol), the port must be enabled. For details, see "CEP Enrollment," on page 395."

Changing a Port Number

To change a port number:

1. Stop the CS instance; see "Starting, Stopping, and Restarting CS Instances" on page 246.
2. Go to the CS configuration directory: <server_root>/cert-<instance_id>/config
3. Open the server.xml file in a text editor and edit the appropriate port numbers:
   • To change the administration port, locate this line and edit the value of the port attribute:

<LS id="admin" ip="0.0.0.0" port="8200" security="on" acceptorthreads="1" blocking="no">

• To change the agent port, locate this line and edit the value of the port attribute:

<LS id="agent" ip="0.0.0.0" port="8100" security="on" acceptorthreads="1" blocking="no">

• To change the end-entity HTTP port, locate this line and edit the value of the port attribute:

<LS id="ee_nonSSL" ip="0.0.0.0" port="80" security="off" acceptorthreads="1" blocking="no">

• To change the end-entity HTTPS port, locate this line and edit the value assigned to port:
  1. Locate the following lines and delete them:

<LS id="ee_nonSSL" ip="0.0.0.0" port="80" security="off" acceptorthreads="1" blocking="no">

<CONNECTIONGROUP id="ee_nonSSL_default" matchingip="default" servername="<hostname.domainname>" defaultvs="ee-vs"/>

1. Locate the following line:

<VS id="ee-vs" state="on" urlhosts="<hostname>.<domainname>" mime="mime1" aclids="acl1" connections="eeSSL_default ee_nonSSL_default">

and change it to:

<VS id="ee-vs" state="on" urlhosts="<hostname>.<dopmainame>" mime="mime1" aclids="acl1" connections="eeSSL_default">

4. If you don't want end-entity interaction with a subsystem, for example, if you don't want end entities to interact with a Certificate Manager, you can remove this port too (in addition to the HTTP port).
5. Save your changes.
6. Restart CS.

Changing an IP Addresses

You can configure CS instances to listen to specific IP addresses. For example, you can install the Certificate Manager and Data Recovery Manager on a single host, in separate instances, and then configure the instances so that the Certificate Manager is served on one IP address and the Data Recovery Manager is served on another address, if the host is configured with more than one IP address.

To configure a CS instance to listen to specific IP addresses:

1. Stop the CS instance.
2. Go to the CS configuration directory: <server_root>/cert-<instance_id>/config
3. Open the server.xml file in a text editor. and edit the appropriate IP addresses:
   • To change the administration ip address, locate this line and edit the value of the ip attribute:

<LS id="admin" ip="0.0.0.0" port="8200" security="on" acceptorthreads="1" blocking="no">

• To change the agent ip address, locate this line and edit the value of the ip attribute:

<LS id="agent" ip="0.0.0.0" port="8100" security="on" acceptorthreads="1" blocking="no">

• To change the end-entity HTTP ip address, locate this line and edit the value of the ip attribute:

<LS id="ee_nonSSL" ip="0.0.0.0" port="80" security="off" acceptorthreads="1" blocking="no">

• To change the end-entity HTTPS ip address, locate this line and edit the value of the ip attribute:

<LS id="eeSSL" ip="0.0.0.0" port="443" security="on" acceptorthreads="1" blocking="no">

4. Save your changes and close the file.
5. Restart the CS instance; see "Starting, Stopping, and Restarting CS Instances" on page 246.

The Internal Database

Each instance of CS uses a Red Hat Directory Server instance as its internal database. When you install a CS instance, an internal database is created for that instance. The install program also allows you to share a directory server between two or more instances.

You can change the internal database used by a CS instance. This section describes how to change that instance and how to restrict access to the internal database.

Caution

The internal database schema is preconfigured for storing CS data only. Do not make any changes to it or configure CS to use any other LDAP directory. Doing so can result in loss of data. Also, do not use this database for any other purpose.

About the Internal Database

CS performs various certificate and key-management functions in response to the requests it receives. These functions include the following:

• Storing and retrieving of certificate issuance requests
• Storing and retrieving of certificate records
• Storing of CRLs
• Storing of ACLs
• Storing of privileged user and role information
• Storing and retrieving of end users' encryption private key records

To fulfill these functions, CS maintains a persistent store-a preconfigured Red Hat Directory Server-referred to as the internal database or local database. The internal database is installed automatically as a part of the CS installation. It is used as an embedded database exclusively by CS and can be managed using Directory management tools that come with Red Hat Directory Server.

The Directory Server instance used for the internal database is different from the LDAP-compliant directory that you use to manage your corporate wide data (users and groups, their certificates, CRLs, and so on).

• In Red Hat Console, you can distinguish an internal database instance from other Directory Server instances. It is in this form:

<CS_instance_id>-db

<CS_instance_id> is the ID of the CS instance that is using the database. You first specified this when you installed this server.

• If you check the files installed under <server_root>, the internal database instance appears like this: slapd-<CS_instance_id>-db

Keep in mind that the subsystems use the database for storing different objects. A Certificate Manager stores all the data, certificate issuance requests, certificates, CRLs, and related information; a Registration Manager only stores the certificate issuance requests it receives; and a Data Recovery Manager only stores key records and related data.

Changing the Internal Database Configuration

To change the Directory Server instance that a CS instance uses as its internal database:

1. Log in to the CS console (see "Logging Into the CS Console" on page 239).
2. Select the Configuration tab, and then in the right pane, select the Internal Database tab.
3. Change a Directory Server instance by changing the following fields:

Host name. Type the fully qualified host name of the machine on which Red Hat Directory Server is installed. CS uses this name to access the directory. The format for the host name is as follows:

<machine_name>.<your_domain>.<domain>

By default, the host name of the Directory Server instance being used as the internal database is shown as localhost instead of the actual host name (for example, certificates.example.com). This is done on purpose to insulate the internal database from being visible outside the system-that is, a server on localhost can only be accessed from the local machine. Thus, the default configuration minimizes the risk of someone connecting to this Directory Server instance from outside the local machine.

You can configure the host name to something other than localhost if you know what you are doing and you think you can limit the visibility of the internal database to a local subnet. For example, if you installed CS and Directory Server on separate machines for load balancing, you will have to specify the host name of the machine in which Directory Server is installed.

Port number. Type a TCP/IP port number; CS uses this port for non-SSL communications with the Directory Server instance that is functioning as the internal database. Make sure that the port you specify is unique on the host system.

Directory manager DN. Type the distinguished name (DN) of an entry in your LDAP directory that has directory manager access. CS will use this DN when it accesses the directory tree to communicate with the directory.

4. To save your changes, click Save.

The CS configuration is modified. If the changes you made require you to restart the server, you will be prompted accordingly. In that case, restart the server.

Enable SSL Client Authentication with the Internal Database

1. Stop CS
2. Go to the directory <server-root>/cert-<id>/config.
3. Open the file CS.cfg in a text editor.
4. Edit the following lines to the indicated values:

internaldb.ldapauth.authtype=SslClientAuth
internaldb.ldapauth.bindDN=CN=Directory Manager
internaldb.ldapauth.bindPWPrompt=Internal LDAP Database
internaldb.ldapconn.host=<ldap_hostname>
internaldb.ldapconn.port=<ldap_httpsport>
internaldb.ldapconn.secureConn=true
internaldb.ldapauth.clientCertNickname=Server-Cert cert-<instance_name>

5. Go to the Directory Server console.
6. Create an entry for the suffix which matches the subject DN of the CS subsystem certificate for the subsystem using this internal database. For example if your CA server certificate has a the subject name c=jupiter.example.com,ou=marketing,o=example,l=mv,c=us then create a suffix o=example,l=mv,c=us. To do this:
   1. Go to Configuration Tab.
   2. Right click and select Data.
   3. Click on New Suffix and add the suffix
7. Go to Directory tab and Right click "DirectoryServer".
8. Add the entry created in Step 6 into the Configuration Administrators group.
9. Click "set Access Control Permission" and then Click Add.
10. Fill in the following information:

ACIName. clientauth

Check all the rights in the Rights tab.

Click This Entry in the Targets tab.

11. Click OK.

Restricting Access to the Internal Database

Red Hat Console displays an entry or icon for the Directory Server instance that CS uses as its internal database. You can distinguish an internal database instance from other Directory Server instances. It is in this form: slapd-<CS_instance_id>-db

Unlike the CS console, access to which is restricted to users with CS administrator privileges, the Directory Server console can be accessed by the person who has privileges to access Red Hat Console. That is, this person can open the Directory Server console for the internal database and make changes to the data stored there. For example, this person can make changes to the CS administrators group, such as deleting existing users and adding entries for self.

If you are concerned about this, you can restrict access to the internal database to only those users who know its Directory Manager DN and corresponding password. You can change this password by modifying the single sign-on password cache. For instructions, check the section that explains how to change the password of an entry in the password cache in Chapter 3, "Password Cache Utility" of CS Command-Line Tools Guide.

1. Log in to Red Hat Console (see "Logging Into the CS Console" on page 239).
2. Select the entry that corresponds to the internal database to which you want to restrict access, and click Open.

The Directory Server console appears.

3. Select the Configuration tab.
4. In the navigation tree, expand Plug-ins, and then select Pass Through Authentication.
5. In the right pane, deselect "Enable plugin" option.
6. Click Save to save your changes.

You are prompted to restart the server.

7. Click the Tasks tab and click "Restart the Directory Server."
8. Close the Directory Server console.
9. When the server is restarted, from Red Hat Console, open the Directory Server console.

The "Login to Directory" dialog box appears; the Distinguished Name field displays the Directory Manager DN and you're required to enter the password that corresponds to this entry.

The Directory Server console (for the internal database) opens only if you enter the correct password.

Managing the Certificate Database

Each CS instance has a certificate database, which is maintained in its internal token. This database contains certificates belonging to the subsystem installed in the CS instance and various CA certificates the subsystems use for validating the certificates they receive.

Whether you use an internal token or an external token for generating and storing key pairs, CS always maintains its list of trusted and untrusted CA certificates in its internal token.

You may need to add new certificates to the database, remove unwanted certificates from the database, or change the trust settings of CA certificates in the database. This section explains how to view the contents of the certificate database, delete unwanted certificates, and change the trust settings of CA certificates installed in the database using the CS window. For information on adding certificates to the database, see "Certificate Setup Wizard" on page 289.

Note	CS also provides a command-line utility called certutil for managing its certificate database. For details about this tool, check this site: http://www.mozilla.org/projects/security/pki/nss/tools/

Viewing and Deleting Certificate Database Content

As an administrator, you should periodically check the contents of the certificate database and make sure that it doesn't include any unwanted CA certificates. For example, if the database includes CA certificates that you don't ever want to trust in your PKI setup, you should delete them.

Removing unwanted certificates also reduces the size of the certificate database.

Note

When deleting CA certificates from the certificate database, be careful not to delete the intermediate CA certificates, which help a subsystem chain up to the trusted CA certificate. If in doubt, leave the certificates in the database as untrusted CA certificates; see "Changing the Trust Settings of a CA Certificate" on page 286.

To view the contents of the database:

1. Log in to the CS window (see "Logging Into the CS Console" on page 239).
2. Select the Configuration tab, and then in the right pane, select the Encryption tab.
3. Click Manage Certificate.

The Certificate Database Management window appears.

The window lists the certificates.

For each certificate, you see the following information:

Certificate Name. Specifies the nickname of the certificate.

Expiry Date. Specifies the date (and time) on which the certificate expires.

Trust Status. Specifies whether the CA is trusted or untrusted. To change the trust setting, see "Changing the Trust Settings of a CA Certificate" on page 286.

list is a table, with each certificate occupying a row.

4. To delete a certificate:
   1. select the CA certificate you want to delete, and click Delete.
   2. When prompted, confirm the delete action.
   3. Click Close.
5. To save your changes, click Save.

Changing the Trust Settings of a CA Certificate

CS relies on the CA certificates in its certificate database for validating certificates it receives during an SSL-enabled communication.

You may need to change the status of a currently trusted CA to untrusted (or vice versa) temporarily or permanently. By making the CA certificate untrusted, you can prevent entities whose certificates have been signed by that CA from successfully authenticating to CS. You can then return the trust option to trusted when the CA notifies you that the problem has been resolved.

If you want to untrust a CA permanently, you should consider removing its certificate from the trust database altogether. For instructions, see "Viewing and Deleting Certificate Database Content" on page 285.

To change the trust setting of a CA certificate:

1. Log in to the CS window (see "Logging Into the CS Console" on page 239).
2. Select the Configuration tab, and then in the right pane, select the Encryption tab.
3. Click Manage Certificate.

The Certificate Database Management window appears.

The window lists the certificates currently installed for the selected CS instance; the list is a table, with each certificate occupying a row.

4. Select the CA certificate whose trust setting you want to modify, and click Edit.

The Certificate Information window appears.

The window shows detailed information about the selected certificate, including serial number, validity period, subject name, issuer name, certificate fingerprint, and trust status.

If the certificate you selected is currently trusted, the window shows a button named "Change to Untrusted." If it is untrusted, the window shows a button named "Change to Trusted."

5. Click "Change to Untrusted" or "Change to Trusted," as appropriate.
6. Click Close.

You are returned to the Certificate Database Management window. The certificate now shows a different trust status.

7. Click Close.

You are returned to the Encryption tab.

8. To save your changes, click Save.

The CS configuration is modified. If the changes you made require you to restart the server, you will be prompted accordingly. In that case, restart the server.

Installing a New CA Certificate in the Certificate Database

You may need to install new trusted CA certificates in the certificate database of a CS instance. For example, assume that you renewed the signing certificate of a Registration Manager. Also assume that the CA that signed the Registration Manager's certificate is not included in the trust database of the Certificate Manager that has been configured to sign certificate requests from this Registration Manager.

When the Registration Manager attempts to request a service from the Certificate Manager (using the renewed certificate for SSL client authentication), the Certificate Manager fails to authenticate the Registration Manager. This happens because, as a part of validating the certificate presented by the Registration Manager, the Certificate Manager checks its certificate database for the CA that signed the Registration Manager's certificate. The Certificate Manager does not find the CA listed in its trust database as a trusted CA, so it rejects the Registration Manager's service request.

The Certificate Setup Wizard built into the CS window automates the process of installing trusted CA certificates in the certificate database. For instructions on using the wizard, see "Using the Wizard to Install a Certificate or Certificate Chain" on page 299.

Note	Be sure to choose the "Other Trusted CAs" option in Step 2 of the wizard process.

Installing a CA Certificate Chain in the Certificate Database

Any client or server software that supports certificates maintains a collection of trusted CA certificates in its certificate database. These CA certificates determine which other certificates the software can validate-in other words, which issuers of certificates the software can trust. In the simplest case, the software can validate only certificates issued by one of the CAs for which it has a certificate. It's also possible for a trusted CA certificate to be part of a chain of CA certificates, each issued by the CA above it in a certificate hierarchy; for details on certificate hierarchies and certificate chains, see "How CA Certificates Are Used to Establish Trust" in Appendix D of Managing Servers with Red Hat Console.

Certificate Setup Wizard

CS provides a wizard, called the Certificate Setup Wizard, which automates the process of requesting and installing the certificates required by the CS manager-Certificate Manager, Registration Manager, Data Recovery Manager, or Online Certificate Status Manager-installed in a CS instance.

The Certificate Setup Wizard is integrated into the CS window, enabling you to accomplish the following tasks:

• Renew certificates of the CS managers installed in a CS instance; renewing a certificate means getting a new certificate with the same subject name and public and private key material as that of the existing certificate, but with an extended validity period.
• Request and install new certificates for the CS managers installed in a CS instance; reissuing or requesting a new certificate means getting a certificate based on a new public and private key pair.
• Install CA certificates in the certificate or trust database of a CS instance.
• Install CA certificate chains in the certificate database of a CS instance.

When you start the wizard, which you do by clicking the Certificate Setup Wizard button in the Encryption tab of the CS window, you are asked to specify whether you want to request or install a certificate. The wizard presents you with the screens appropriate to your choice and walks you through the entire process.

For installing certificates, except for cases when the certificate is self-signed by the CA, you will need to run the wizard twice: once, to request the certificate and once to install the certificate. The reason for this is, if you submit the certificate request to a non-local CA, you will have to wait for the certificate until it is delivered to you.

The following sections explain the process of requesting and installing a certificate by using the Certificate Setup Wizard:

• Using the Wizard to Request a Certificate
• Using the Wizard to Install a Certificate or Certificate Chain

Using the Wizard to Request a Certificate

The Certificate Setup Wizard allows you to request any of the certificates used by the Certificate Manager, Registration Manager, Data Recovery Manager, or Online Certificate Status Manager installed in the currently selected CS instance.

Using the wizard to request a certificate involves the following steps:

• Step 1. Select the Operation
• Step 2. Choose the Certificate
• Step 3. Specify the Key-Pair Information
• Step 4. Specify the Subject Name for the Certificate
• Step 5. Specify the Validity Period
• Step 6. Specify Extensions
• Step 7. Copy the Certificate Signing Request
• Step 8. Check the Certificate Request Status

Step 1. Select the Operation

Indicate whether you want to request a certificate or install a certificate.

For the purposes of completing the instructions that follow, assume that you chose to request a certificate.

Step 2. Choose the Certificate

Choose the certificate (by name) that you want to request.

The drop-down list shows various certificates used by the currently selected CS instance. Choose the one you want to request-which certificates you see in the list depends on the subsystems installed in the currently selected CS instance. You may see a combination of the following options:

• If a Certificate Manager is installed, the list includes the Certificate Manager's CA signing, OCSP signing, and SSL server certificates.
• If a Registration Manager is installed, the list includes the Registration Manager's signing, and SSL server certificates.
• If a Data Recovery Manager is installed, the list includes the Data Recovery Manager's transport, and SSL server certificate.
• If a Online Certificate Status Manager is installed, the list includes the Online Certificate Status Manager's signing, and SSL server certificate.

Depending on the certificate you want to generate, choose the one in the drop-down list:

• Certificate Manager Signing Certificate-choose this option if you want to request a signing certificate for the Certificate Manager. If you choose this option, you must also specify whether the certificate request is for a self-signed CA (also known as the root CA) or a subordinate CA.
• Certificate Manager OCSP Signing Certificate-choose this option if you want to request an OCSP signing certificate for the Certificate Manager.
• Data Recovery Manager Transport Certificate-choose this option if you want to request a transport certificate for the Data Recovery Manager.
• Online Certificate Status Manager Signing Certificate-choose this option if you want to request a signing certificate for the Online Certificate Status Manager.
• Registration Manager Signing Certificate-choose this option if you want to request a signing certificate for the Registration Manager.
• SSL Server Certificate-choose this option if you want to generate an SSL server certificate request for the CS manager.
• Other-choose this option if you want to generate a certificate request for a certificate that is not generated by a CS manager by default. For example, in a Certificate Manager, you can use this option to request a CRL signing certificate or a separate SSL client certificate exclusively for authenticating to the publishing directory. Be sure to specify the certificate type in the adjoining field. By default only two certificate types are supported: caCrlSigning for the CRL signing certificate and client for SSL client certificate (see "Getting an SSL Client Certificate for a Subsystem" on page 311)

Step 3. Specify the Key-Pair Information

Specify the key-pair information for the certificate to be requested.

You need to identify the following:

• The token that contains the key pair for generating the certificate request-the drop-down list shows the names of tokens currently installed for the selected CS instance; these are the tokens you can use now.
  • The internal token is identified as internal. You should choose this option if the key pair for the certificate you chose in the previous step is stored in the local key database.
  • The names of external tokens vary, matching the names specified when the tokens were installed. You should choose this option if the key pair for the certificate you chose in the previous step is in an external cryptographic device. If you don't see the token you want to use, exit from the wizard, make sure the token is installed properly, restart the server, and repeat the process. For information on using or installing external tokens, see "External Token" on page 306.
• The key pair for generating the certificate request-you can choose to generate the certificate request based on an existing or a new key pair.
  • If you want to renew the certificate you selected in the previous step, use the existing key pair for generating the request. For example, you can extend the validity period of a certificate by renewing it.

  To generate a certificate request based on an existing key pair, select the token that contains the key pair you want to use for generating the request. The wizard automatically selects the key pair that corresponds to the certificate you chose in the previous step.

  • If you want a new certificate, use a new key pair for generating the request. For example, you may want to get a new SSL server certificate or may want to replace an existing certificate whose private key has been compromised.

  To generate a certificate request based on a new key pair, select the token that can generate the key pair you want to use for generating the request. For example, if you want to generate the key pair using an external cryptographic device, such as a smart card, select that as the token. In addition, you will be required to indicate details, such as the key algorithm and size for the key pair.

• The type and length of the key pair-you are required to provide this information only if you chose to generate the certificate request based on a new key pair. For key type, you can choose RSA or DSA. Be sure to select a key type that the CA (to which you will later submit the request for signing) can certify.

For key length, enter the size in bits.

• If the key type is RSA, the key size can be 512, 768, 1024, 2048, 4096, or Custom.
• If the key type is DSA, the key size can be 512, 1024, or Custom (which must be in increments of 64 bit).

Keep in mind that generating a new key pair takes time-the longer the key length the longer the time the wizard takes to generate it.

Step 4. Specify the Subject Name for the Certificate

Specify the subject name, in distinguished name (DN) format, for the certificate to be requested. Note that you will see this screen only if you chose to generate the certificate for a new key pair.

You can either enter values for individual DN attributes required to build the subject DN or build the complete subject DN string yourself. If you enter values for individual DN attributes, the wizard constructs the subject DN string.

If you want to enter values for individual DN components, provide the following information:

• Common name-enter the name as appropriate. Except for the SSL server certificate, the common name format can be a descriptive name of up to 255 characters. For example, you can name the Certificate Manager's signing certificate as "Root CA for Example Corporation"; similarly, you can name the Registration Manager's signing certificate as "Registration Authority for North America". For a SSL server certificate, the name must be the fully qualified host name of CS in this form: <machine_name>.<your_domain>.<domain>

To determine the machine and domain names, go to Red Hat Console, and locate the CS host in the navigation tree.

• Organizational unit-enter the organizational unit the server belongs to. For example, Marketing.
• Organization-enter a description that identifies your organization. For example, Example Corporation.
• Locality-enter the name of the city where your business is located. For example, Mountain View.
• State or province-enter the name of the state or province where your business is located. For example, California.
• Country-enter the name of the country where your business is located. For example, US.

Step 5. Specify the Validity Period

You need to complete this step only if you chose to generate a self-signed CA certificate request.

Specify the starting and ending dates of the validity period for the certificate request you want to generate. You can also specify the time at which the validity period should start and end on those dates.

The default validity period is two years.

Step 6. Specify Extensions

You need to complete this step only if you chose to generate a CA signing certificate request for a Certificate Manager (deployed as either the root CA or a subordinate CA).

This screen allows you to set the standard X.509 version 3 extensions and Red Hat-defined extensions for the certificate to be requested. The required extensions are chosen by default. If you want to change the default choices, be sure to read the general guidelines explained in Appendix G, "Certificate and CRL Extensions."

Also note that certificate extensions are required if you are setting up a hierarchy of certificate authorities (CAs). Subordinate CAs must have certificates that include the extension identifying them as either a subordinate SSL CA (which allows them to issue certificates for SSL) or a subordinate email CA (which allows them to issue certificates for secure email). If you disable certificate extensions, you will not be able to set up CA hierarchies. For more information on CA hierarchies, see "Certificate Hierarchies" in Appendix D of Managing Servers with Red Hat Console.

You can set the following extensions:

• Basic constraints-select this option if you want to set any of the basic constraints extension bits in the certificate you are requesting. When you select the option, the associated fields are enabled. You should select the ones you want to set.
• Netscape certificate type-select this option if you want to set any of the Netscape Certificate Type extension bits in the certificate you are requesting. When you select the option, the associated fields are enabled. You should select the ones you want to set.
• Authority key identifier-select this option if you want to set the authority key identifier extension in the certificate you are requesting.
• Subject key identifier-select this option if you want to set the subject key identifier extension in the certificate you are requesting.
• Key usage-select this option if you want to set the key usage extension in the certificate you are requesting. If you choose this option, the digital signature (bit 0), non repudiation (bit 1), key Certificate Sign (bit 5), and CRL sign (bit 6) bits are set by default. The extension is marked critical as recommended by the PKIX standard and RFC 2459 (see http://www.ietf.org/rfc/rfc2459.txt for a description of the Key Usage extension).
• Extension in MIME 64 DER encoding-select this option if you want to specify any custom extension. When you select the option, the associated text field is enabled. You should paste your extension (in MIME 64 DER encoded format) into the text field.

CS provides tools that generate MIME-64 encoded blobs for many standard extensions. You can use these tools for generating MIME-64 encoded blobs for any extensions that you may want to include in CA and other certificate requests. For details about these tools, check this directory in your CS installation: <server_root>/bin/cert/tools

Note that the text field provided for pasting the extension in general accepts a single extension blob. If you want to add multiple extensions, you should use the ExtJoiner program, which is also provided in the tools directory mentioned above. For instructions to use the program, see Chapter 5, "Extension Joiner Tool" of CS Command-Line Tools Guide.

Step 7. Copy the Certificate Signing Request

Based on the information you've entered in the previous steps, the wizard now displays the certificate signing request (CSR).

The request is in a base-64 encoded PKCS #10 format and is bounded by the marker lines -----BEGIN NEW CERTIFICATE REQUEST----- and -----END NEW CERTIFICATE REQUEST-----. An example is show below:

-----BEGIN NEW CERTIFICATE REQUEST-----

MIICJzCCAZCgAwIBAgIBAzANBgkqhkiG9w0BAQQFADBC6SAwHgYDVQQKExdOZXRzY2FwZSBDb21tdW5pY2
F0aW9uczngjhnMVQ2VydGlmaWNhdGUgQXV0aG9yaXR5MB4XDTk4MDgyNzE5MDAwMFoXDTk5MDIyMzE5MDA
wMnbjdgngYoxIDAeBgNVBAoTF05ldHNjYXBlIENvbW11bmljYXRpb25zMQ8wDQYDVQQLEwZQZW9wbGUxFz
AVBgoJkiaJkIsZAEBEwdzdXByaXlhMRcwFQYDVQQDEw5TdXByaXlhIFNoZXR0eTEjMCEGCSqGSIb3Dbndg
JARYUc3Vwcml5Yhvfggsvwryw4y7214vAOBgNVHQ8BAf8EBAMCBLAwFAYJYIZIAYb4QgEBAQHBAQDAgCAM
A0GCSqGSIb3DQEBBAUAA4GBAFi9FzyJlLmS+kzsue0kTXawbwamGdYql2w4hIBgdR+jWeLmD4CP4x

-----END NEW CERTIFICATE REQUEST-----

The wizard also copies the CSR to a text file it creates in the configuration directory, which is located at <server_root>/cert-<instance_id>/config. The name of the text file varies depending on for which key pair you generated the request. Table 8-4 lists them.

Table 8-4 Names of files created for certificate signing requests  

Filename	Certificate Signing Request
cacsr.txt	Certificate Manager CA signing certificate
ocspcsr.txt	Certificate Manager OCSP signing certificate
racsr.txt	Registration Manager signing certificate
kracsr.txt	Data Recovery Manager transport certificate
ocspcsr.txt	Online Certificate Status Manager signing certificate
sslcsr.txt	SSL server certificate
othercsr.txt	Other certificates, such as Certificate Manager CRL signing certificate or SSL client certificate

Do not modify the CSR; you must send it to the CA as it is. You can either submit the request automatically or copy the request and manually submit it to the CA by visiting the URL it provides for this purpose. Note that the wizard's auto-submission feature-a feature that enables you to send the request directly to a remote CA without having to manually copy the base-64 encoded certificate and paste the request in an enrollment form-can be used to submit requests to a remote Certificate Manager or Registration Manager (if that Certificate Manager is configured to receive requests via the Registration Manager) only. It can't be used for submitting the request to a third-party CA. For a third-party CA, you must manually copy the certificate request and paste it into the text area provided in the CA's enrollment form.

Sending the CSR Automatically to a CS Manager

To send the certificate signing request (CSR) automatically to a Certificate Manager:

1. Type the appropriate values in the following fields:

Send the request to a remote CS now. Select this option.

Host name. Type the fully-qualified host name (in the <machine_name>.<your_domain>.<domain> format) of the Certificate Manager to which you want to submit your request automatically. For example, CAmachine.example.com.

EE port number. Type the end-entity port number. For example, 80.

Yes, it's the SSL secure server port. Select this option if the end entity port number you specified is the SSL port for end entities.

2. Click Next to submit your request to the CA.

The Certificate Manager returns a request ID for your request. Note the request ID as you can use it later to get the certificate from the Certificate Manager to which you submitted the request.

The request you submitted gets queued for agent approval-an agent needs to process and approve the certificate request, which the CA signs then and delivers back to the email address specified in the request. You can contact the CA agent to find out when the certificate will be delivered to you. If you have agent privileges to the Certificate Manager, you can log in to its agent interface and approve the request yourself.

3. Once the certificate has been issued, you can use the request ID to import the certificate into the wizard. Alternatively, you can also install the certificate following the instructions in "Using the Wizard to Install a Certificate or Certificate Chain" on page 299.

Sending the CSR Manually to an Internal CA

The following instructions assume that your internally deployed CA is a Certificate Manager and that you are using the default HTML forms provided for end-entity enrollment. If you have customized these forms, you should follow the appropriate instructions.

To send the certificate signing request (CSR) manually to an internal CA:

1. Copy the CSR, including the marker lines -----BEGIN NEW CERTIFICATE REQUEST----- and -----END NEW CERTIFICATE REQUEST-----, to a text file.
2. Open a web browser window.
3. Enter the URL to the CA's home page.

By default, the CA's home page is the end entity services interface. Depending on the port at which the CA is listening to end-entity requests (see "Changing a Port Number" on page 278) the URL to the end entity services is one of the following:

http://<hostname>:<end_entity_port> or https://<hostname>:<end_entity_port>, where <hostname> is in the form <machine_name>.<your_domain>.<domain>

The end entity services interface appears.

4. Click the Enrollment tab.
5. In the menu list, click the appropriate link the type of certificate you are getting.
6. In the form that appears, enter the required information and paste the CSR from either the clipboard or text file.

For information on how a form works, click the Help button provided on the form. Be sure to include the marker lines, -----BEGIN NEW CERTIFICATE REQUEST----- and -----END NEW CERTIFICATE REQUEST-----.

7. Submit the request.
8. When the CA sends you a response, save the information in a text file for future reference or inquiry.

Note that the you submitted gets queued for agent approval-an agent needs to process and approve the certificate request, which the CA signs then and delivers back to the email address specified in the request. You can contact the CA agent to find out when the certificate will be delivered to you. If you have agent privileges to the Certificate Manager, you can approve the request yourself.

9. When you receive the certificate from the CA, you'll need to install it following the instructions in "Using the Wizard to Install a Certificate or Certificate Chain" on page 299.

Sending the CSR to an External CA

An external CA is any public or third-party CA. Before sending the CSR to a public CA, make sure that the CA can issue the certificate you want to request. Also, it is a good idea to read the policy statement published by a CA to see whether the CA imposes any restrictions on the validity period or usage of the certificate.

To send the CSR manually to an external or third-party CA:

1. Copy the CSR, including the marker lines -----BEGIN NEW CERTIFICATE REQUEST----- and -----END NEW CERTIFICATE REQUEST-----, to a text file.
2. Open a web browser window.
3. Navigate to the CA's home page by entering the appropriate URL in the browser window.
4. Locate the form that allows you to submit certificate requests for servers.
5. Enter the required information and paste the CSR from the text file.
6. Submit the request.
7. When the CA sends you a response, save the information in a text file for future reference or inquiry.
8. When you receive the certificate from the CA, install it following the instructions in "Using the Wizard to Install a Certificate or Certificate Chain" on page 299.

Step 8. Check the Certificate Request Status

The wizard now informs you of the status of the request.

• If you requested a self-signed CA certificate, the wizard automatically submits the CSR to the CA. If the CSR includes all the required information, the CA signs the certificate and returns it to the wizard, which then installs it in the appropriate token.
• If you requested any other certificate, you must get the certificate from the CA and install it using the process outlined in "Using the Wizard to Install a Certificate or Certificate Chain" on page 299.

Using the Wizard to Install a Certificate or Certificate Chain

The Certificate Setup Wizard allows you to install or import the following certificates into either an internal or external token used by the currently selected CS instance:

• Any of the certificates used by a Certificate Manager, Registration Manager, Data Recovery Manager, and Online Certificate Status Manager
• Any other trusted CA certificates (certificates of CAs that you want to trust)
• Certificate chains

A certificate chain typically includes a collection of certificates: the subject certificate, the trusted root CA certificate, and any intermediate CA certificates needed to link the subject certificate to the trusted root. However, the certificate chain the wizard allows you to import must include only CA certificates; none of the certificates can be a user certificate.

In a certificate chain, each certificate in the chain is encoded as a separate DER-encoded object. When the wizard imports a certificate chain, it imports these objects one after the other, all the way up the chain to the last certificate, which may or may not be the root CA certificate. If any of the certificates in the chain already exist in the local certificate database, the wizard replaces them by the ones included in the chain. If the chain includes intermediate CA certificates, the wizard adds them to the certificate database as untrusted CA certificates.

The certificate or certificate chain you provide to the wizard for installation must be in one of the data formats supported by the wizard. This is explained in "Data Formats for Installing Certificates and Certificate Chains" on page 300.

Using the wizard to install a certificate or certificate chain involves the following steps, described in detail on page 301:

• Step 1. Select the Operation
• Step 2. Select the Certificate or Certificate Chain
• Step 3. Specify the Location of the Certificate
• Step 4. View the Certificate or Certificate Chain
• Step 5. Install the Certificate or Certificate Chain
• Step 6. Verify the Certificate Status

Data Formats for Installing Certificates and Certificate Chains

The wizard can accept certificates and certificate chains in several data formats. This section briefly explains the data formats recognized by the wizard.

Binary Formats

The wizard can recognize certificates and certificate chains in the following binary formats:

• DER-encoded certificate-This is a single binary DER-encoded certificate.
• PKCS #7 SignedData objects-This is a PKCS #7 SignedData object. The only significant field in the SignedData object is the certificate. In particular, the signature and the contents are ignored. The PKCS #7 format allows multiple certificates to be downloaded at once.
• DER-encoded certificates-These are DER-encoded certificates that may or may not be wrapped in a base-64 encoding package surrounded by the delimiters -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.
• Red Hat Certificate Sequence-This is a simpler format for downloading certificate chains. It consists of a PKCS #7 ContentInfo structure, wrapping a sequence of certificates. The value of the contentType field should be redhat-cert-sequence, while the content field is the following structure:

CertificateSequence ::= SEQUENCE OF Certificate

This format allows multiple certificates to be downloaded at once.

Text Formats

The wizard can also import certificates and certificate chains in text formats. Here's what you should be aware of when using the wizard to install a certificate or certificate chain in text format:

The text format must begin with the following line:

-----BEGIN CERTIFICATE-----

Following this line should be the certificate data, which can be in any of the binary formats described in "Binary Formats" on page 300. This data should be base-64 encoded as described by RFC 1113 (for details, see http://www.scit.wlv.ac.uk/rfc/rfc11xx/RFC1113.html).

Following the certificate data must be this line:

-----END CERTIFICATE-----

Step 1. Select the Operation

Indicate whether you want to request a certificate or install a certificate.

For the sake of completing the instructions that follow, assume that you chose to install a certificate.

Step 2. Select the Certificate or Certificate Chain

Select the certificate you want to install.

The drop-down list shows various options. Depending on whether you want to install a CS certificate, any other trusted CA certificate, or a CA certificate chain, choose the appropriate option from the list box:

• Certificate Manager Signing Certificate-choose this option if you want to install a CA signing certificate for the Certificate Manager installed in the currently selected CS instance.
• OCSP Signing Certificate-choose this option if you want to install an OCSP signing certificate for the Certificate Manager installed in the currently selected CS instance.
• Registration Manager Signing Certificate-choose this option if you want to install a request signing certificate for the Registration Manager installed in the currently selected CS instance.
• Data Recovery Manager Transport Certificate-choose this option if you want to install a transport certificate for the Data Recovery Manager installed in the currently selected CS instance.
• Online Certificate Status Manager Signing Certificate-choose this option if you want to install a signing certificate for the Online Certificate Status Manager installed in the currently selected CS instance.
• SSL Server Certificate-choose this option if you want to install an SSL server certificate for the CS managers installed in the currently selected CS instance.
• Trusted CA Certificate Chain-choose this option if you want to install a trusted CA certificate chain; the CA certificate will be included in the chain.
• Cross-Signed Certificate-choose this option if you want to install a cross-signed certificate.
• Untrusted CA Certificate Chain-choose this option if you want to install an untrusted CA certificate chain.

Step 3. Specify the Location of the Certificate

Locate the certificate or certificate chain you want to install.

You can keep the certificate or certificate chain in a text file or copy it to the text area on the wizard screen. Here is some information that will help you decide on the location.

• Keeping the certificate or certificate chain in a text file-the wizard can import a certificate or certificate chain from a text file in text as well as binary formats; see "Data Formats for Installing Certificates and Certificate Chains" on page 300. If you have copied the certificate or certificate chain to a text file, you will be required to provide the wizard with the absolute path to that file. The file must be located in the host system the wizard is running. If the file is located elsewhere, exit from the wizard, copy the file to the local disk, and restart the wizard.
• Copying the certificate or certificate chain to the text area on the wizard screen-you can paste the certificate or certificate chain into the text area provided by the wizard. This is a text input field, so you can paste the certificate or certificate chain in text format only. For example, if you are installing a certificate, it base-64 encoded certificate blob should look similar to this:

-----BEGIN CERTIFICATE-----

MIICKzCCAZSgAwIBAgIBAzANgkqkiG9w0BAQQFADA3MQswCQYDVQQGEwJVUzERMA8GA1UEChMITmV0c2Nh
cGUxFTATBgNVBAsTDFN1cHJpeWEncyBDQTAeFw05NzEwMTgwMTM2MjVaFw05OTEwMTgwMTM2MjVaMEgxCz
AJBgNVBAYTAlVTMREwDwYDVQQKEwhOZXRzY2FwZTENMAsGA1UECxMEUHawczEXMBUGA1UEAxMOU3Vwcml5
YSBTaGV0dHkwgZ8wDQYJKoZIhdfNAQEBBQADgY0AMIGJAoGBAMr6eZiPGfjX3uRJgEjmKiqG7SdATYzBcA
Bu1AVyd7chRFOGD3wNktbf6hRo6EAmM5R1Askzf8AW7LiQZBcrXpc0k4du+2j6xJu2MPm8WKuMOTuvzpo+
SGXelmHVChEqooCwfdiZywyZNmgaMa2MS6pUkfQVAgMBAAGjNjA0MBEGCWCGSAGG+EIBAQQEAwIAgD

-----END CERTIFICATE-----

• The certificate is at the CS where your request was sent- if you have previously sent the certificate request to a remote Certificate Manager automatically and have noted the request ID that you received in return, you can use it to retrieve the certificate from the Certificate Manager.

Step 4. View the Certificate or Certificate Chain

The wizard displays the certificate or certificate chain you have chosen to install. Make sure you have chosen the right one; otherwise, use the Back button to go back and locate the right one. Specify a nickname for the certificate.

Step 5. Install the Certificate or Certificate Chain

The wizard shows the certificate or certificate chain information you have selected for installing. You should check the information to make sure that you have chosen the correct one for installing.

After verifying that the certificate you have chosen is the correct one, click the Install button. The wizard installs the certificate or the CA chain in the token you have chosen.

• If you installed a certificate that has been issued by CA whose certificate chain doesn't exist in the certificate database, you must add that CA's certificate chain to the database. To add the CA chain to the database, copy the CA chain to a text file, start the wizard again, and install the CA chain.
• If you installed (or imported) a certificate chain, the wizard adds (to the local trust database) the first certificate in the chain as a trusted CA certificate and any subsequent certificates as untrusted CA certificates. For more information on how the wizard installs a certificate chain, see "Using the Wizard to Install a Certificate or Certificate Chain" on page 299.

Step 6. Verify the Certificate Status

This step is applicable only if you installed a certificate chain.

After you install a certificate chain in the trust database of a CS instance, check the trust status of each certificate that got installed, and make sure that the correct CA certificates are trusted. For instructions, see "Changing the Trust Settings of a CA Certificate" on page 286.

Consideration When Getting New Certificates for the Subsystems

You may need to get new certificates for the CS manager installed in a CS instance. Getting a new certificate means getting a certificate based on a new public and private key pair.

The sections that follow explain how to get new certificates for a Certificate Manager, Registration Manager, Data Recovery Manager, and Online Certificate Status Manager using the Certificate Setup Wizard. Alternatively, you can use the command-line utility called the Certificate Database tool (certutil). For details about this tool, check this site:

Getting a new certificate for a CS manager requires careful planning. This section provides some guidelines that will help you request and install the new certificate.

Determine which certificate you want to get

You can get CA signing, OCSP signing, CRL signing, and SSL server certificates for the Certificate Manager; signing and SSL server certificates for the Registration Manager; transport and SSL server certificates for the Data Recovery Manager; and signing and SSL server certificates for the Online Certificate Status Manager. For details about certificates used by a CS manager.

• If you have deployed a Certificate Manager as your root CA and if you want to get a new self-signed CA certificate for that Certificate Manager, you must consider the possible effects on your PKI setup of changing the key pair of the root CA. If you reissue the Certificate Manager's CA signing certificate with a new key material, none of the certificates issued or signed by the CA using its old key will work; the reason for this is, when you change the root CA key, all certificates that rely on the CA certificate for validation will no longer be validated. For example, if the CA has issued certificates to subordinate Certificate Managers, Registration Managers, Data Recovery Managers, Online Certificate Status Managers, and agents, all those certificates will become invalid-the subsystems will fail to function, and agents will fail to access agent interfaces.

Before getting a new self-signed certificate for the Certificate Manager, therefore, you must address issues involved in deploying the new root CA certificate across your enterprise. Because each deployment would have very specific requirements, it is beyond the scope of this document to explain how you should deploy the new CA certificate.

• If you have deployed a Certificate Manager as a subordinate CA (that's chained to a root CA) and if you want to get a new subordinate CA certificate for that Certificate Manager, you must consider the possible effects on your PKI setup of changing the key pair of the subordinate CA. When you change the subordinate CA key, all certificates that rely on the subordinate CA certificate for validation will no longer be validated. Before getting a new subordinate certificate, therefore, you must plan to address issues involved in deploying the new subordinate CA certificate across you enterprise.
• If you have deployed a Certificate Manager and if you have configured it to publish CRLs to a Online Certificate Status Manager, you will need to identify the Certificate Manager to the Online Certificate Status Manager again.
• If you want to get a new signing certificate for a Registration Manager, check whether the Registration Manager has been set up as a trusted manager for a Certificate Manager and Data Recovery Manager-that is, you must identify the subsystems that have been configured to receive requests from this Registration Manager; see "Trusted Managers" on page 317. You will need to replace the existing signing certificate with the new one in all these subsystems.
• If you want to get a new transport certificate for a Data Recovery Manager, you must identify the end-entity interfaces or forms that have been set up for the archival of end users' encryption private keys; see "How Key Archival Works" on page 190. You will need to replace the existing transport certificate with the new one in all these forms.
• If you want to get a new SSL server certificate for a Certificate Manager, determine whether the Certificate Manager has been cloned as part of a cloned-CA setup. If it has, you'll have to update the clone CAs certificate databases with the new SSL server certificate.

Also determine whether the Certificate Manager is configured to publish certificates and CRLs to an LDAP directory and whether it uses the SSL server certificate for SSL client authentication to the directory. If it does, you will have to request the certificate with the appropriate extensions, and after installing the certificate you will have to configure the publishing directory to use this certificate.

• You can get any number of SSL server certificates.

Tokens for Storing CS Keys and Certificates

A token is a hardware or software device that performs cryptographic functions and optionally stores public-key certificates, cryptographic keys, and data defined by the application using the cryptographic services. Alternatively, a token can also be considered as a device that you can use to generate and store your key pairs and corresponding certificates.

Certificate System defines two types of tokens, internal and external, for storing key pairs and certificates that belong to the Certificate Manager, Registration Manager, Data Recovery Manager, and Online Certificate Status Manager.

Note	Only those who have the password that protects a token can access it. For information on changing this password, use the certutil tool. The documentation for the tool can be found here: http://www.mozilla.org/projects/security/pki/nss/tools/

Internal Token

An internal (software) token refers to a pair of software files, usually called certificate database and key database, that Certificate System uses to generate and store its key pairs and certificates. Certificate System automatically generates these files in the file system of its host machine when you choose to use the internal token for the first time. These files were created for you during CS installation if you chose to use the internal token for key-pair generation.

In the CS host system, the certificate database is identified by the name cert-<instance_id>-<machine_name>-cert8.db; the key database is identified by the name cert-<instance_id>-<machine_name>-key3.db. You can find both these files in the <server_root>/alias directory.

External Token

An external (hardware) token refers to an external hardware device, such as a smart card, FORTEZZA card, or other crypto card, that Certificate System uses to generate and store its key pairs and certificates. Certificate System supports any hardware tokens that are compliant with PKCS#11 version 2.01.

If you haven't already done so, consider using external tokens for generating and storing the key pairs and certificates used by Certificate System. These devices represent another security measure you can take to safeguard private keys because hardware tokens are sometimes considered more secure than software tokens. For additional details, check the literature provided by hardware-token vendors.

Installing External Tokens

To use external encryption devices or tokens, you need to take the following steps:

• Install the Cryptographic Device
• Install the PKCS #11 Module

Install the Cryptographic Device

To install the drivers provided by the device manufacturer, follow the instructions that came with the device. When you install a hardware token, you are given an opportunity to name it; be sure to use a name that will help you identify the token later.

Install the PKCS #11 Module

PKCS #11 is a standard set of APIs and shared libraries used by Red Hat and a number of encryption vendors. PKCS #11 isolates an application from the details of the cryptographic device, thus enabling the application to provide a unified interface for PKCS #11-compliant cryptographic devices.

The PKCS #11 module implemented in Certificate System (in Red Hat Administration Server) enables it to support cryptographic devices supplied by many different manufacturers. Specifically, it allows Certificate System to plug in shared libraries or DLLs supplied by manufacturers of external encryption devices and use them for generating and storing keys and certificates for the CS managers.

There are two ways in which you can install a PKCS #11 module, by using the interface provided within Red Hat Console or by using the command-line utility named modutil. Both the methods are documented below.

• To install the PKCS #11 module using Red Hat Console:
  1. Log in to the CS window (see "Logging Into the CS Console" on page 239).
  2. From the Console menu, choose Manage PKCS#11.

The PKCS #11 Management window appears.

1. Click Add.

The Add PKCS #11 Module window appears.

1. Enter information as appropriate. If you choose JAR as your file type, you are required to provide the path to the JAR file that contains the DLLs. If you choose DLL as your file type, in addition to the path to the DLL you are also required to provide a name for the module you're attempting to install (so as to help you identify it easily later). The sample in the figure shows how you would install an nCipherTM token.

Pick DLL to add a UNIX shared/dynamic library, which on a Solaris machine is identified with the .so extension.

1. Click OK.
• To install the PKCS #11 module using the modutil tool:
  1. Locate the CS instance for which you want to install the PKCS #11 module.
  2. Open a terminal window.
  3. Go to the alias directory: <server_root>/alias
  4. At the prompt, enter this command:

<server_root>/shared/bin/modutil -dbdir . -nocertdb -create
 

This creates the required security module database file (secmod.db) in the Administration Server's configuration directory.

1. At the prompt, enter this command:

<server_root>/shared/bin/modutil -dbdir . -nocertdb 

-add <module_name> -libfile <library_file>
 
  

    
  <library_file> specifies the path to the DLL or other library file containing the implementation of the PKCS #11 interface module.
    
  <module_name> specifies the name of the PKCS #11 module (which you specified in Step 1 when you installed the drivers).
  

Managing Tokens Used by the Subsystems

There are two main tasks involved in managing the tokens used by Certificate System:

• Viewing Tokens
• Changing a Token's Password

Viewing Tokens

To view a list of the tokens currently installed for a CS instance:

1. Log in to the CS window (see "Logging Into the CS Console" on page 239).
2. Select the Configuration tab, and then in the right pane, select the Encryption tab.
3. In the Map To section, check the Token drop-down list.

It shows the names (as specified when the tokens were installed) of external tokens installed for the currently selected CS instance. For information on installing external tokens, see "External Token" on page 306.

Changing a Token's Password

The token, internal or external, that stores the key pairs and certificates for the subsystems is protected (encrypted) by a password. To decrypt the key pairs or to gain access to them, you must enter that password. The first time you specified this password is when you used the token the first time, most likely during CS installation.

It is good security practice to periodically change the password that protects your server's keys and certificates; changing the password periodically minimizes the risk of someone finding out the password. To change a token's password, use the certutil command-line utility, the documentation for which can be found at this site: http://www.mozilla.org/projects/security/pki/nss/tools/

Note that the single sign-on password cache stores the passwords for tokens in order to start the server using a single password; for details, see "Starting, Stopping, and Restarting CS Instances" on page 246. Whenever you change the password, the cache is updated with the new password.

Hardware Cryptographic Accelerators

Certificate System allows you to use hardware cryptographic accelerators with external tokens. Many of the accelerators provide the following security features:

• Fast SSL connections-speed is important if you want your Certificate Manager, Registration Manager, or Data Recovery Manager to be able to accommodate a high number of simultaneous enrollment or service requests.
• Hardware protection of private keys-these devices behave like smart cards, in that they do not allow the private keys to be copied or removed from the hardware token. This is important if you are concerned about the risks associated with key theft from an active attacker of your online Registration Manager or Certificate Manager.

Configuring the Server's Security Preferences

Configuring a CS manager's security preferences involves identifying the following:

• The SSL server certificates a server must use for authenticating to the end entity, agent, and administration interfaces. For details, see "Configuring the Server to Use Separate SSL Server Certificates" on page 310.
• The SSL client certificate a Certificate Manager must use for authenticating to the publishing directory (if the Certificate Manager is configured to publish certificates and CRLs to the directory). For details, see "Getting an SSL Client Certificate for a Subsystem" on page 311.
• The version of SSL that an instance of CS must use during SSL communication. The latest version is SSL version 3, but many older clients use SSL version 2. Because client authentication is required for performing privileged operations, you must enable SSL version 3 ciphers supported by CS. For details, see "Configuring the Server's Security Preferences," on page 309.

Configuring the Server to Use Separate SSL Server Certificates

You can configure a CS instance to use separate SSL server certificates for authenticating to Red Hat Console, the Agent Services interface, and the end entity services interface.

This configuration involves the following steps:

• Step 1. Get the Required SSL Server Certificates
• Step 2: Update the Configuration

Step 1. Get the Required SSL Server Certificates

You must first request and install the required number of SSL server certificates for the particular CS instance. For instructions, see "Consideration When Getting New Certificates for the Subsystems" on page 303.

Once you have installed the certificates, you should be able to see them in the list of SSL server certificates in the Encryption tab of the CS window.

Step 2: Update the Configuration

After you verify that the certificates are installed, configure the server as follows:

1. Stop the CS instance; see "Starting, Stopping, and Restarting CS Instances" on page 246.
2. Go to this directory: <server_root>/cert-<instance_id>/config
3. In a text editor, open the server.xml file.
4. Locate the servercertnickname parameter for the interface of your interest.
   • To change the certificate used for authenticating to the Agent Services interface, edit the value assigned to the servercertnickname parameter in the id="agent" section.
   • To change the certificate used for authenticating to the end-entity services interface, edit the value assigned to the servercertnickname parameter in the id="ee_nonSSL" section.
   • To change the certificate used for authenticating to the SSL-enabled end-entity services interface, edit the value assigned to the servercertnickname parameter in the id="eeSSL" section.
   • To change the certificate used for authenticating to the administration interface, Red Hat Console, edit the value assigned to the servercertnickname parameter in the id="admin" section.
5. Save your changes and close the file.
6. Start the server; see "Starting, Stopping, and Restarting CS Instances" on page 246.

Getting an SSL Client Certificate for a Subsystem

By default, the Certificate Manager uses its SSL server certificate for SSL client authentication to the publishing directory.

If you want the Certificate Manager to use another certificate for authenticating to the publishing directory, you can do so. This section provides instructions for requesting and installing an SSL client certificate for a Certificate Manager and configuring it to use that certificate for SSL client authentication to the publishing directory.

1. Log in the CS console, see "Logging Into the CS Console" on page 239.
2. Select the Configuration tab, and then select the Encryption tab.
3. Click the Certificate Setup Wizard button to launch the wizard, which is explained in "Certificate Setup Wizard" on page 289.
4. Select the option to request a certificate and then follow the on-screen prompts to generate a certificate request for the client certificate-in the Certificate Selection window, select Other and specify client as the certificate type in the associated text field.
5. Once you have the certificate request ready, submit it to a CA so that it can issue a certificate. For general instructions to use the wizard to request a certificate, see section "Using the Wizard to Request a Certificate" on page 289.
6. If you submitted the request to a Certificate Manager and if you have agent privileges for that Certificate Manager, log in to its Agent Services interface, locate the request, and check the request for required extensions. (If you submitted the request to any other CA, you must ask the person managing that CA to make the same changes to the request before approving it.)

Make sure that only the SSL Client option for certificate type is selected in the request. For certificates with no Netscape Certificate Type extensions, the Key Usage extension must be included with Signing and Encryption bits set.

7. Approve the request.
8. Once you have the certificate ready, restart the wizard and install the certificate in the Certificate Manager's database. For general instructions to use the wizard to add a certificate, see "Using the Wizard to Install a Certificate or Certificate Chain" on page 299.

Note that the default nickname for the certificate is
crlSigningCert cert-<instance_id>, where <instance_id> identifies the CS instance in which the Certificate Manager is installed.

9. After you've installed the certificate successfully, go to the Tasks tab and stop the Certificate Manager.
10. Configure the Certificate Manager to use this certificate.

After you install the certificate, configure the Certificate Manager to use the new certificate for SSL client authentication to the publishing directory. For instructions, see.

Check the Certificate Database for the CA Certificate

The CA that signed the agent's SSL client certificate must be trusted by the subsystem that services requests from the agent. Make sure that this CA's certificate exists in the subsystem's certificate database (internal or external) and that it is trusted. To check whether the CA's certificate exists in your subsystem's certificate database, follow the instructions in "Managing the Certificate Database" on page 285.

• If the CA certificate isn't listed, follow the instructions in "Using the Wizard to Install a Certificate or Certificate Chain" on page 299 and add the certificate to the certificate database.
• If the CA's certificate is listed but untrusted, follow the instructions in "Changing the Trust Settings of a CA Certificate" on page 286 and change the trust setting to trusted.