此内容没有您所选择的语言版本。
2.2. Overview of Certificate System Subsystems
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:
- Reads in its default
name=valuepairs from a plain text configuration file (/etc/pki/default.cfg). - Interactively or automatically overrides any pairs as specified and stores the final result as a Python dictionary.
- Executes an ordered series of scriptlets to perform subsystem and instance installation.
- 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.
- The configuration servlet utilizes this data to configure a new PKI subsystem, and then passes control back to the
pkispawnexecutable, 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:
#mkdir -p /root/pki- Use a text editor such as vim to create a configuration file named
/root/pki/ca.cfgwith the following contents:[DEFAULT] pki_admin_password=<password> pki_client_pkcs12_password=<password> pki_ds_password=<password>
#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:
#pkidestroySubsystem (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-tomcatLog 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-tomcatdWithwatchdogdisabledpki-tomcatd-nuxwdogWithwatchdogenabled
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 usingsystemctl.
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.
| 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
