Chapter 6. Installing and Configuring Certificate System

The Certificate System is comprised of subsystems which can be independently installed on different servers, multiple instances installed on a single server, and other flexible configurations for availability, scalability, and failover support. The procedures for downloading, installing, and configuring instances of Certificate System subsystems are described in this chapter.
There are different paths for the installation process, depending on the planning decisions that you made and the needs of your environment.
The Certificate System servers include six subsystems:
  • Certificate Authority (CA)
  • Registration Authority (RA)
  • Data Recovery Manager (DRM), sometimes referred to as a Key Recovery Authority (KRA)
  • Online Certificate Status Protocol (OCSP) Responder
  • Token Key Service (TKS)
  • Token Processing System (TPS)
Each subsystem is installed and then configured individually. The order in which subsystems are configured is very important because of the basic relationships which are established between subsystems at the time they are installed. For example, every subsystem depends on a certificate authority; the TPS also depends on a TKS and (optionally) DRM.
Order of Subsystem Configuration

Figure 6.1. Order of Subsystem Configuration


The installation process includes not only setting up the individual subsystems but also setting up the environment. The environment configuration is flexible and largely optional; the configuration that you select should depend on the existing network environment and security requirements.
The complete subsystem setup process includes the preparation for the environment, the instance creation and setup, and then the configuration of major features for each subsystem.
This chapter covers the basic installation procedures for general PKI subsystems and the token management system. Other installation options are covered in other chapters:

6.1. About pkicreate

Certificate System subsystem instances are created and defined using a script called pkicreate. This script creates individual subsystem instances, with user-defined settings like the configuration and log directories and port numbers. After the instance is created, it is then configured through the HTML-based configuration wizard or by using the pkisilent script.
The syntax for pkicreate is slightly different between subsystems because of the different port and groups configurations. Table 6.1, “pkicreate Parameters”

TIP

To get full usage examples and syntax for the pkicreate command, run pkicreate --help.

Table 6.1. pkicreate Parameters

Parameter Description
pki_instance_root Gives the full path to the new instance configuration directory.
subsystem_type Gives the type of subsystem being created.
pki_instance_name Gives the name of the new instance. Instance names must be unique on a single machine, but do not have to be unique within the security domain (since instances are identified by hostname and port, not instance name).
secure_port[a] Sets a single SSL port number for the subsystem. This parameter is required if port separation is not configured, meaning that separate ports are not assigned for the administrator, agent, and end-entities services.
agent_secure_port[a] Sets the SSL port for the agent web services. If this is specified, then both ee_secure_port and admin_secure_port must be specified. For CAs only, an end-entities client authentication port is also required with the ee_secure_client_auth_port option.
ee_secure_port[a] Sets the SSL port for the end-entities web services. If this is specified, then both agent_secure_port and admin_secure_port must be specified. For CAs only, an end-entities client authentication port is also required with the ee_secure_client_auth_port option.
ee_secure_client_auth_port[a] For CAs only. Sets the SSL port for the end-entity client authentication. If this is specified, then ee_secure_port, agent_secure_port, and admin_secure_port must be specified.
admin_secure_port[a] Sets the SSL port number for the administrator services, usually the pkiconsole. If this is specified, then both agent_secure_port and ee_secure_port must be specified. For CAs only, an end-entities client authentication port is also required with the ee_secure_client_auth_port option.
non_clientauth_secure_port[a] Sets the end entities SSL port for RA and TPS subsystems.
unsecure_port[a] Sets the regular port number. If this is not set, the number is randomly generated. Still, it is recommended that administrators set this value to make sure there are no conflicts with SELinux labels for other services.
tomcat_server_port[a] Sets the port number for the Tomcat web server for CA, OCSP, TKS, and DRM instances.
redirect conf Optional. Sets the location for the configuration files for the new instance. This should include an instance-specific directory name in the path. For example, for the pki-ca instance, this should be something like /etc/pki-ca.
redirect logs Optional. Sets the location for the log files for the new instance. This should include an instance-specific directory name in the path. For example, for the pki-ca instance, this should be something like /var/log/pki-ca.
user Optional. Sets the user as which the Certificate System instance will run.
group Optional. Sets the group as which the Certificate System instance will run.
audit_group Optional. Gives the name of the group for auditors for the TPS instance. The default is pkiaudit, if this option is not given.
sans_security_manager Optional. For the CA, OCSP, DRM, and TKS. Configures the new instance to run without a Java Security Manager. This option should not be used for subsystems in a Common Criteria environment.
[a] The ports selected for the new instance should not conflict with any other ports assigned on the host or SELinux. Check the /etc/services file to see port assignments for the system. Then, run semanage port -l |grep port# to check SELinux; if there is no output, then there is no conflict with SELinux assignments.

For more information on the pkicreate tool options, see the Certificate System Command-Line Tools Guide.