Search
SupportConsoleDevelopersStart a trialContact

2.2. Overview of Certificate System Subsystems

download PDF

2.2.1. Separate versus Shared Instances

Red Hat Certificate System supports deployment of separate PKI instances for all subsystems:
  • Separate PKI instances run as a single Java-based Apache Tomcat instance.
  • Separate PKI instances contain a single PKI subsystem (CA, KRA, OCSP, TKS, or TPS).
  • Separate PKI instances must utilize unique ports if co-located on the same physical machine or virtual machine (VM).
Alternatively, Certificate System supports deployment of a shared PKI instance:
  • Shared PKI instances also run as a single Java-based Apache Tomcat instance.
  • Shared PKI instances that contain a single PKI subsystem are identical to a separate PKI instance.
  • Shared PKI instances may contain any combination of up to one of each type of PKI subsystem:
    • CA only
    • TKS only
    • CA and KRA
    • CA and OCSP
    • TKS and TPS
    • CA, KRA, TKS, and TPS
    • CA, KRA, OCSP, TKS, and TPS
    • etc.
  • Shared PKI instances allow all of their subsystems contained within that instance to share the same ports.
  • Shared PKI instances must utilize unique ports if more than one is co-located on the same physical machine or VM.

2.2.2. Instance Installation Prerequisites

2.2.2.1. Directory Server Instance Availability

Prior to installation of a Certificate System instance, a local or remote Red Hat Directory Server LDAP instance must be available. For instructions on installing Red Hat Directory Server, see Red Hat Directory Server Installation Guide.

2.2.2.2. PKI Packages

Red Hat Certificate System is composed of packages listed below:
  • The following base packages form the core of Certificate System, and are available in base Red Hat Enterprise Linux repositories:
    • pki-core.el7
      • pki-base
      • pki-base-java
      • pki-ca
      • pki-javadoc
      • pki-kra
      • pki-server
      • pki-symkey
      • pki-tools
  • The packages listed below are not available in the base Red Hat Enterprise Linux  subscription channel. To install these packages, you must first use Subscription Manager to attach the Red Hat Certificate System subscription pool, and enable the RHCS9 repository. See the Subscription Manager chapter of the Red Hat Enterprise Linux 7 System Administrator's Guide for instructions.
    • pki-console.el7pki
      • pki-console
    • pki-core.el7pki
      • pki-ocsp
      • pki-tks
      • pki-tps
    • redhat-pki.el7pki
      • redhat-pki
    • redhat-pki-theme.el7pki
      • redhat-pki-console-theme
      • redhat-pki-server-theme
Use a Red Hat Enterprise Linux 7 system (optionally, use one that has been configured with a supported Hardware Security Module listed in Chapter 4, Supported Platforms), and make sure that all packages are up to date before installing Red Hat Certificate System.
To install all Certificate System packages (with the exception of pki-javadoc), use use Yum to install the redhat-pki metapackage: 
# yum install redhat-pki
Alternatively, install one or more of the top level PKI subsystem packages as required; see the list above for exact package names. If you use this approach, make sure to also install the redhat-pki-server-theme package, and optionally redhat-pki-console-theme and pki-console to use the PKI Console.
Finally, developers and administrators may also want to install the JSS and PKI javadocs (the jss-javadoc and pki-javadoc).

Note

The jss-javadoc package requires you to enable the Server-Optional repository in Subscription Manager.

2.2.2.3. Instance Installation and Configuration

The pkispawn command line tool is used to install and configure a new PKI instance. It eliminates the need for separate installation and configuration steps, and may be run either interactively, as a batch process, or a combination of both (batch process with prompts for passwords). The utility does not provide a way to install or configure the browser-based graphical interface.
For usage information, use the pkispawn --help command.
The pkispawn command:
  1. Reads in its default name=value pairs from a plain text configuration file (/etc/pki/default.cfg).
  2. Interactively or automatically overrides any pairs as specified and stores the final result as a Python dictionary.
  3. Executes an ordered series of scriptlets to perform subsystem and instance installation.
  4. The configuration scriptlet packages the Python dictionary as a JavaScript Object Notation (JSON) data object, which is then passed to the Java-based configuration servlet.
  5. The configuration servlet utilizes this data to configure a new PKI subsystem, and then passes control back to the pkispawn executable, which finalizes the PKI setup. A copy of the final deployment file is stored in /var/lib/pki/instance_name/<subsystem>/registry/<subsystem>/deployment.cfg
See the pkispawn man page for additional information.
The default configuration file, /etc/pki/default.cfg, is a plain text file containing the default installation and configuration values which are read at the beginning of the process described above. It consists of name=value pairs divided into [DEFAULT], [Tomcat], [CA], [KRA], [OCSP], [TKS], and [TPS] sections.
If you use the -s option with pkispawn and specify a subsystem name, then only the section for that subsystem will be read.
The sections have a hierarchy: a name=value pair specified in a subsystem section will override the pair in the [Tomcat] section, which in turn override the pair in the [DEFAULT] section. Default pairs can further be overriden by interactive input, or by pairs in a specified PKI instance configuration file.

Note

Whenever non-interactive files are used to override default name=value pairs, they may be stored in any location and specified at any time. These files are referred to as myconfig.txt in the pkispawn man pages, but they are also often referred to as .ini files, or more generally as PKI instance configuration override files.
See the pki_default.cfg man page for more information.
The Configuration Servlet consists of Java bytecode stored in /usr/share/java/pki/pki-certsrv.jar as com/netscape/certsrv/system/ConfigurationRequest.class. The servlet processes data passed in as a JSON object from the configuration scriptlet using pkispawn, and then returns to pkispawn using Java bytecode served in the same file as com/netscape/certsrv/system/ConfigurationResponse.class.
An example of an interactive installation only involves running the pkispawn command on a command line as root: 
# pkispawn

Important

Interactive installation currently only exists for very basic deployments. For example, deployments intent upon using advanced features such as cloning, Elliptic Curve Cryptography (ECC), external CA, Hardware Security Module (HSM), subordinate CA, and others, must provide the necessary override parameters in a separate configuration file.
A non-interactive installation requires a PKI instance configuration override file, and the process may look similar to the following example: 
  1. # mkdir -p /root/pki
  2. Use a text editor such as vim to create a configuration file named /root/pki/ca.cfg with the following contents: 
    [DEFAULT]
pki_admin_password=<password>
pki_client_pkcs12_password=<password>
pki_ds_password=<password>
  3. # pkispawn -s CA -f /root/pki/ca.cfg
See the pkispawn man page for various configuration examples.

2.2.2.4. Instance Removal

To remove an existing PKI instance, use the pkidestroy command. It can be run interactively or as a batch process. Use pkidestroy -h to display detailed usage inforamtion on the command line.
The pkidestroy command reads in a PKI subsystem deployment configuration file which was stored when the subsystem was created (/var/lib/pki/instance_name/<subsystem>/registry/<subsystem>/deployment.cfg), uses the read-in file in order to remove the PKI subsystem, and then removes the PKI instance if it contains no additional subsystems. See the pkidestroy man page for more information.
An interactive removal procedure using pkidestroy may look similar to the following: 
# pkidestroy
Subsystem (CA/KRA/OCSP/TKS/TPS) [CA]:
Instance [pki-tomcat]:

Begin uninstallation (Yes/No/Quit)? Yes

Log file: /var/log/pki/pki-ca-destroy.20150928183547.log
Loading deployment configuration from /var/lib/pki/pki-tomcat/ca/registry/ca/deployment.cfg.
Uninstalling CA from /var/lib/pki/pki-tomcat.
rm '/etc/systemd/system/multi-user.target.wants/pki-tomcatd.target'

Uninstallation complete.
A non-interactive removal procedure may look similar to the following example: 
# pkidestroy -s CA -i pki-tomcat
Log file: /var/log/pki/pki-ca-destroy.20150928183159.log
Loading deployment configuration from /var/lib/pki/pki-tomcat/ca/registry/ca/deployment.cfg.
Uninstalling CA from /var/lib/pki/pki-tomcat.
rm '/etc/systemd/system/multi-user.target.wants/pki-tomcatd.target'

Uninstallation complete.

2.2.3. Execution Management (systemctl)

2.2.3.1. Starting, Stopping, Restarting, and Obtaining Status

Red Hat Certificate System subsystem instances can be stopped and started using the systemctl execution management system tool on Red Hat Enterprise Linux 7: 
# systemctl start <unit-file>@instance_name.service
# systemctl status <unit-file>@instance_name.service
# systemctl stop <unit-file>@instance_name.service
# systemctl restart <unit-file>@instance_name.service
<unit-file> has one of the following values: 
pki-tomcatd 			With watchdog disabled
pki-tomcatd-nuxwdog 		With watchdog enabled
For more details on the watchdog service, refer to the Section 2.3.10, “Passwords and Watchdog (nuxwdog)” and Section 13.3.2, “Using the Certificate System Watchdog Service”.

2.2.3.2. Starting the Instance Automatically

The systemctl utility in Red Hat Enterprise Linux  7 manages the automatic startup and shutdown settings for each process on the server. This means that when a system reboots, some services can be automatically restarted. System unit files control service startup to ensure that services are started in the correct order. The systemd service and systemctl utility are described in the Red Hat Enterprise Linux System Administrator's Guide
Certificate System instances can be managed by systemctl, so this utility can set whether to restart instances automatically. After a Certificate System instance is created, it is enabled on boot. This can be changed by using systemctl: 
# systemctl disable pki-tomcatd@instance_name.service
To re-enable the instance: 
# systemctl enable pki-tomcatd@instance_name.service

Note

The systemctl enable and systemctl disable commands do not immediately start or stop Certificate System.

2.2.4. Process Management (pki-server and pkidaemon)

2.2.4.1. The pki-server Command Line Tool

The primary process management tool for Red Hat Certificate System is pki-server. Use the pki-server --help command and see the pki-server man page for usage information.
The pki-server command-line interface (CLI) manages local server instances (for example server configuration or system certificates). Invoke the CLI as follows: 
$ pki-server [CLI options] <command> [command parameters]
The CLI uses the configuration files and NSS database of the server instance, therefore the CLI does not require any prior initialization. Since the CLI accesses the files directly, it can only be executed by the root user, and it does not require client certificate. Also, the CLI can run regardless of the status of the server; it does not require a running server.
The CLI supports a number of commands organized in a hierarchical structure. To list the top-level commands, execute the CLI without any additional commands or parameters: 
$ pki-server
Some commands have subcommands. To list them, execute the CLI with the command name and no additional options. For example: 
$ pki-server ca
$ pki-server ca-audit
To view command usage information, use the --help option: 
$ pki-server --help
$ pki-server ca-audit-event-find --help

2.2.4.2. Enabling and Disabling an Installed Subsystem Using pki-server

To enable or disable an installed subsystem, use the pki-server utility. 
# pki-server subsystem-disable -i instance_id subsystem_id
# pki-server subsystem-enable -i instance_id subsystem_id
Replace subsystem_id with a valid subsystem identifier: ca, kra, tks, ocsp, or tps.

Note

One instance can have only one of each type of subsystem.
For example, to disable the OCSP subsystem on an instance named pki-tomcat: 
# pki-server subsystem-disable -i pki-tomcat ocsp
To list the installed subsystems for an instance: 
# pki-server subsystem-find -i instance_id
To show the status of a particular subsystem: 
# pki-server subsystem-find -i instance_id subsystem_id

2.2.4.3. The pkidaemon Command Line Tool

Another process management tool for Red Hat Certificate System is the pkidaemon tool: 
pkidaemon {start|status} instance-type [instance_name]
  • pkidaemon status tomcat - Provides status information such as on/off, ports, URLs of each PKI subsystem of all PKI instances on the system.
  • pkidaemon status tomcat instance_name - Provides status information such as on/off, ports, URLs of each PKI subsystem of a specific instance.
  • pkidaemon start tomcat instance_name.service - Used internally using systemctl.
See the pkidaemon man page for additional information.

2.2.4.4. Finding the Subsystem Web Services URLs

The CA, KRA, OCSP, TKS, and TPS subsystems have web services pages for agents, as well as regular users and administrators, when appropriate. These web services can be accessed by opening the URL to the subsystem host over the subsystem's secure end user's port. For example, for the CA: 
https://server.example.com:8443/ca/services

Note

To get a complete list of all of the interfaces, URLs, and ports for an instance, check the status of the service. For example: 
pkidaemon status instance_name
The main web services page for each subsystem has a list of available services pages; these are summarized in Table 2.1, “Default Web Services Pages”. To access any service specifically, access the appropriate port and append the appropriate directory to the URL. For example, to access the CA's end entities (regular users) web services: 
https://server.example.com:8443/ca/ee/ca
If DNS is not configured, then an IPv4 or IPv6 address can be used to connect to the services pages. For example: 
https://192.0.2.1:8443/ca/services
https://[2001:DB8::1111]:8443/ca/services

Note

Anyone can access the end user pages for a subsystem. However, accessing agent or admin web services pages requires that an agent or administrator certificate be issued and installed in the web browser. Otherwise, authentication to the web services fails.
Table 2.1. Default Web Services Pages
Port Used for SSL/TLS Used for Client Authentication[a] Web Services Web Service Location
Certificate Manager     
8080 No End Entities ca/ee/ca
8443 Yes No End Entities ca/ee/ca
8443 Yes Yes Agents ca/agent/ca
8443 Yes No Services ca/services
8443 Yes No Console pkiconsole https://host:port/ca
Key Recovery Authority     
8080 No End Entities[b] kra/ee/kra
8443 Yes No End Entities[b] kra/ee/kra
8443 Yes Yes Agents kra/agent/kra
8443 Yes No Services kra/services
8443 Yes No Console pkiconsole https://host:port/kra
Online Certificate Status Manager     
8080 No End Entities[c] ocsp/ee/ocsp
8443 Yes No End Entities[c] ocsp/ee/ocsp
8443 Yes Yes Agents ocsp/agent/ocsp
8443 Yes No Services ocsp/services
8443 Yes No Console pkiconsole https://host:port/ocsp
Token Key Service     
8080 No End Entities[b] tks/ee/tks
8443 Yes No End Entities[b] tks/ee/tks
8443 Yes Yes Agents tks/agent/tks
8443 Yes No Services tks/services
8443 Yes No Console pkiconsole https://host:port/tks
Token Processing System     
8080 No Unsecure Services tps/tps
8443 Yes Secure Services tps/tps
8080 No Enterprise Security Client Phone Home tps/phoneHome
8443 Yes Enterprise Security Client Phone Home tps/phoneHome
8443 Yes Yes Admin, Agent, and Operator Services [d] tps/ui
[a] Services with a client authentication value of No can be reconfigured to require client authentication. Services which do not have either a Yes or No value cannot be configured to use client authentication.
[b] Although this subsystem type does have end entities ports and interfaces, these end-entity services are not accessible through a web browser, as other end-entity services are.
[c] Although the OCSP does have end entities ports and interfaces, these end-entity services are not accessible through a web browser, as other end-entity services are. End user OCSP services are accessed by a client sending an OCSP request.
[d] The agent, admin, and operator services are all accessed through the same web services page. Each role can only access specific sections which are only visible to the members of that role.

2.2.4.5. Starting the Certificate System Console

The CA, KRA, OCSP, and TKS subsystems have a Java interface which can be accessed to perform administrative functions. For the KRA, OCSP, and TKS, this includes very basic tasks like configuring logging and managing users and groups. For the CA, this includes other configuration settings such as creating certificate profiles and configuring publishing.
The Console is opened by connecting to the subsystem instance over its SSL/TLS port using the pkiconsole utility. This utility uses the format: 
pkiconsole https://server.example.com:admin_port/subsystem_type
The subsystem_type can be ca, kra, ocsp, or tks. For example, this opens the KRA console: 
pkiconsole https://server.example.com:8443/kra
If DNS is not configured, then an IPv4 or IPv6 address can be used to connect to the console. For example: 
https://192.0.2.1:8443/ca
https://[2001:DB8::1111]:8443/ca
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.