2.2. Overview of Certificate System Subsystems
2.2. Overview of Certificate System Subsystems 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 the 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 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 attach a Red Hat Certificate System subscription pool and enable the RHCS repository. For more information, see Section 6.8, "Attaching a Red Hat Subscription and Enabling the Certificate System Package Repository" . pki-core pki-console pki-ocsp pki-tks pki-tps redhat-pki redhat-pki : contains all the packages of the pki-core module. If you wish to pick redhat-pki packages individually, it is advised to disable the pki-core module. redhat-pki-console-theme redhat-pki-server-theme Use a Red Hat Enterprise Linux 8 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 dnf to install the redhat-pki metapackage: Alternatively, you can 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=value pairs 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 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 : 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: Use a text editor such as vim to create a configuration file named /root/pki/ca.cfg with the following contents: 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: A non-interactive removal procedure may look similar to the following example: 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 8: <unit-file> has one of the following values: For more details on the watchdog service, refer to the Section 2.3.10, "Passwords and Watchdog (nuxwdog)" and Section 14.3.2, "Using the Certificate System Watchdog Service" . Note In RHCS 10, these systemctl actions support the pki-server alias: pki-server <command> subsystem_instance_name is the alias for systemctl <command> pki-tomcatd@<instance>.service . 2.2.3.2. Starting the Instance Automatically The systemctl utility in Red Hat Enterprise Linux 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 Configuring basic system settings guide for Red Hat Enterprise Linux 8. 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 : To re-enable the instance: 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: 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: Some commands have subcommands. To list them, execute the CLI with the command name and no additional options. For example: To view command usage information, use the --help option: 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. 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 : To list the installed subsystems for an instance: To show the status of a particular subsystem: 2.2.4.3. The pkidaemon Command Line Tool Another process management tool for Red Hat Certificate System is the pkidaemon tool: 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: 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: 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: If DNS is not configured, then an IPv4 or IPv6 address can be used to connect to the services pages. For example: 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 Important This console is being deprecated. 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: The subsystem_type can be ca , kra , ocsp , or tks . For example, this opens the KRA console: If DNS is not configured, then an IPv4 or IPv6 address can be used to connect to the console. For example:
dnf install redhat-pki pkispawn mkdir -p /root/pki [DEFAULT] pki_admin_password= <password> pki_client_pkcs12_password= <password> pki_ds_password= <password> pkispawn -s CA -f /root/pki/ca.cfg 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. 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. 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 pki-tomcatd With watchdog disabled pki-tomcatd-nuxwdog With watchdog enabled systemctl disable pki-tomcatd@ instance_name .service systemctl enable pki-tomcatd@ instance_name .service pki-server [CLI options] <command> [command parameters] pki-server pki-server ca USD pki-server ca-audit pki-server --help USD pki-server ca-audit-event-find --help pki-server subsystem-disable -i instance_id subsystem_id pki-server subsystem-enable -i instance_id subsystem_id pki-server subsystem-disable -i pki-tomcat ocsp pki-server subsystem-find -i instance_id pki-server subsystem-find -i instance_id subsystem_id pkidaemon {start|status} instance-type [ instance_name ] https://server.example.com:8443/ca/services pkidaemon status instance_name https://server.example.com:8443/ca/ee/ca https://192.0.2.1:8443/ca/services https://[2001:DB8::1111]:8443/ca/services pkiconsole https://server.example.com: admin_port/subsystem_type pkiconsole https://server.example.com:8443/kra https://192.0.2.1:8443/ca https://[2001:DB8::1111]:8443/ca