Chapter 2. Introduction to Red Hat Certificate System

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.

Red Hat Certificate System is composed of packages listed below:

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:

dnf install redhat-pki

# dnf install redhat-pki

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).

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:

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.

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

# pkispawn

A non-interactive installation requires a PKI instance configuration override file, and the process may look similar to the following example:

See the pkispawn man page for various configuration examples.

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

# 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

# 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.

Red Hat Certificate System subsystem instances can be stopped and started using the systemctl execution management system tool on Red Hat Enterprise Linux 8:

systemctl start <unit-file>@instance_name.service

# systemctl start <unit-file>@instance_name.service

systemctl status <unit-file>@instance_name.service

# systemctl status <unit-file>@instance_name.service

systemctl stop <unit-file>@instance_name.service

# systemctl stop <unit-file>@instance_name.service

systemctl restart <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

pki-tomcatd 			With watchdog disabled
pki-tomcatd-nuxwdog 		With watchdog enabled

For more details on the watchdog service, refer to Section 2.3.10, “Passwords and watchdog (nuxwdog)” and Section 9.3.2, “Using the Certificate System watchdog service”.

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:

systemctl disable pki-tomcatd@instance_name.service

# systemctl disable pki-tomcatd@instance_name.service

To re-enable the instance:

systemctl enable pki-tomcatd@instance_name.service

# systemctl enable pki-tomcatd@instance_name.service

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]

$ 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

$ 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

pki-server ca-audit

$ pki-server ca-audit

To view command usage information, use the --help option:

pki-server --help

$ pki-server --help

pki-server ca-audit-event-find --help

$ pki-server ca-audit-event-find --help

To enable or disable an installed subsystem, use the pki-server utility.

pki-server subsystem-disable -i instance_id subsystem_id

# pki-server subsystem-disable -i instance_id subsystem_id

pki-server subsystem-enable -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.

For example, to disable the OCSP subsystem on an instance named pki-tomcat:

pki-server subsystem-disable -i pki-tomcat ocsp

# pki-server subsystem-disable -i pki-tomcat ocsp

To list the installed subsystems for an instance:

pki-server subsystem-find -i instance_id

# pki-server subsystem-find -i instance_id

To show the status of a particular subsystem:

pki-server subsystem-find -i instance_id subsystem_id

# pki-server subsystem-find -i instance_id subsystem_id

Another process management tool for Red Hat Certificate System is the pkidaemon tool:

pkidaemon {start|status} instance-type [instance_name]

# pkidaemon {start|status} instance-type [instance_name]

See the pkidaemon man page for additional information.

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

https://server.example.com:8443/ca/services

pkidaemon status instance_name

pkidaemon status instance_name

The main web services page for each subsystem has a list of available services pages; these are summarized in the below table. 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

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

https://192.0.2.1:8443/ca/services
https://[2001:DB8::1111]:8443/ca/services

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 -d nssdb -n 'optional client cert nickname' https://server.example.com:admin_port/subsystem_type

# pkiconsole -d nssdb -n 'optional client cert nickname' 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 -d nssdb -n 'optional client cert nickname' https://server.example.com:8443/kra

# pkiconsole -d nssdb -n 'optional client cert nickname' 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

https://192.0.2.1:8443/ca
https://[2001:DB8::1111]:8443/ca

Each subsystem contains interfaces allowing interaction with various portions of the subsystem. All subsystems share a common administrative interface and have an agent interface that allows for agents to perform the tasks assigned to them. A CA Subsystem has an end-entity interface that allows end-entities to enroll in the PKI. An OCSP Responder subsystem has an end-entity interface allowing end-entities and applications to check for current certificate revocation status. Finally, a TPS has an operator interface.

While the application server provides the connection entry points, Certificate System completes the interfaces by providing the servlets specific to each interface.

The servlets for each subsystem are defined in the corresponding web.xml file. The same file also defines the URL of each servlet and the security requirements to access the servlets. See Section 2.3.1, “Java application server” for more information.

View larger image

The agent interface provides Java servlets to process HTML form submissions coming from the agent entry point. Based on the information given in each form submission, the agent servlets allow agents to perform agent tasks, such as editing and approving requests for certificate approval, certificate renewal, and certificate revocation, approving certificate profiles. The agent interfaces for a KRA subsystem, or a TKS subsystem, or an OCSP Responder are specific to the subsystems.

In the non-TMS setup, the agent interface is also used for inter-CIMC boundary communication for the CA-to-KRA trusted connection. This connection is protected by SSL client-authentication and differentiated by separate trusted roles called Trusted Managers. Like the agent role, the Trusted Managers (pseudo-users created for inter-CIMC boundary connection only) are required to be SSL client-authenticated. However, unlike the agent role, they are not offered any agent capability.

In the TMS setup, inter-CIMC boundary communication goes from TPS-to-CA, TPS-to-KRA, and TPS-to-TKS.

View larger image

For the CA subsystem, the end-entity interface provides Java servlets to process HTML form submissions coming from the end-entity entry point. Based on the information received from the form submissions, the end-entity servlets allow end-entities to enroll, renew certificates, revoke their own certificates, and pick up issued certificates. The OCSP Responder subsystem’s End-Entity interface provides Java servlets to accept and process OCSP requests. The KRA, TKS, and TPS subsystems do not offer any End-Entity services.

View larger image

The operator interface is only found in the TPS subsystem.

NSS Soft Token is also called an internal token or a software token. The software token consists of two files, which are usually called the certificate database (cert9.db) and key database (key4.db). The files are created during the Certificate System subsystem configuration. These security databases are located in the /var/lib/pki/instance_name/alias directory.

Two cryptographic modules provided by the NSS soft token are included in the Certificate System:

Specific instructions on how to import certificates onto the NSS soft token are in Chapter 10, Managing certificate/key crypto token.

For more information on the Network Security Services (NSS), see Mozilla Developer web pages of the same name.

Any PKCS #11 module can be used with the Certificate System. To use an external hardware token with a subsystem, load its PKCS #11 module before the subsystem is configured, and the new token is available to the subsystem.

Available PKCS #11 modules are tracked in the pkcs11.txt database for the subsystem. The modutil utility is used to modify this file when there are changes to the system, such as installing a hardware accelerator to use for signing operations. For more information on modutil, see Network Security Services (NSS) at Mozilla Developer webpage.

PKCS #11 hardware devices also provide key backup and recovery features for the information stored on hardware tokens. Refer to the PKCS #11 vendor documentation for information on retrieving keys from the tokens.

Specific instructions on how to import certificates and to manage the HSM are in Chapter 10, Managing certificate/key crypto token.

Supported Hardware Security Modules are located in Section 4.4, “Supported Hardware Security Modules”.

Certificate request and serial numbers are represented by Java’s big integers

By default, due to their efficiency, certificate request numbers, certificate serial numbers, and replica IDs are assigned sequentially for CA subsystems.

Serial number ranges are specifiable for requests, certificates, and replica IDs:

For new clones:

All ranges are configurable at CA instance installation time by adding a [CA] section to the PKI instance override configuration file, and adding the following name=value pairs under that section as needed. Default values which already exist in /etc/pki/default.cfg are shown in the following example:

[CA]
pki_serial_number_range_start=1
pki_serial_number_range_end=10000000
pki_request_number_range_start=1
pki_request_number_range_end=10000000
pki_replica_number_range_start=1
pki_replica_number_range_end=100

[CA]
pki_serial_number_range_start=1
pki_serial_number_range_end=10000000
pki_request_number_range_start=1
pki_request_number_range_end=10000000
pki_replica_number_range_start=1
pki_replica_number_range_end=100

In addition to sequential serial number management, Red Hat Certificate System provides optional random serial number management. Using random serial numbers is selectable at CA instance installation time by adding a [CA] section to the PKI instance override file and adding the following name=value pair under that section:

[CA]
pki_random_serial_numbers_enable=True

[CA]
pki_random_serial_numbers_enable=True

If selected, certificate request numbers and certificate serial numbers will be selected randomly within the specified ranges.

The audit log contains records for selectable events that have been set up as recordable events. You can configure audit logs also to be signed for integrity-checking purposes.

Debug logs, which are enabled by default, are maintained for all subsystems, with varying degrees and types of information.

Debug logs for each subsystem record much more detailed information than system, transaction, and access logs. Debug logs contain very specific information for every operation performed by the subsystem, including plugins and servlets which are run, connection information, and server request and response messages.

Services which are recorded to the debug log include authorization requests, processing certificate requests, certificate status checks, and archiving and recovering keys, and access to web services.

The debug logs record detailed information about the processes for the subsystem. Each log entry has the following format:

date time [processor] LogLevel: servlet: message

date time [processor] LogLevel: servlet: message

The message can be a return message from the subsystem or contain values submitted to the subsystem.

For example, the TKS records this message for connecting to an LDAP server:

{YY-MM-DD} [main] INFO: TKS engine started

{YY-MM-DD} [main] INFO: TKS engine started

The processor is main, and the message is the message from the server about TKS engine status, and there is no servlet. The INFO is LogLevel, its value could be INFO, WARNING, SEVERE, depending on the log level.

The CA, on the other hand, records information about certificate operations as well as subsystem connections:

{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.requestowner$ value=KRA-server.example.com-8443

{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.requestowner$ value=KRA-server.example.com-8443

In this case, the processor is the HTTP protocol over the CA’s agent port, while it specifies the servlet for handling profiles and contains a message giving a profile parameter (the subsystem owner of a request) and its value (that the KRA initiated the request).

				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.profileapprovedby$ value=admin
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.cert_request$ value=MIIBozCCAZ8wggEFAgQqTfoHMIHHgAECpQ4wDDEKMAgGA1UEAxMBeKaBnzANBgkqhkiG9w0BAQEFAAOB...
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.profile$ value=true
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.cert_request_type$ value=crmf
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.requestversion$ value=1.0.0
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.req_locale$ value=en
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.requestowner$ value=KRA-server.example.com-8443
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.dbstatus$ value=NOT_UPDATED
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.subject$ value=uid=jsmith, e=jsmith@example.com
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.requeststatus$ value=begin
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.auth_token.user$ value=uid=KRA-server.example.com-8443,ou=People,dc=example,dc=com
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.req_key$ value=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDreuEsBWq9WuZ2MaBwtNYxvkLP^M
				HcN0cusY7gxLzB+XwQ/VsWEoObGldg6WwJPOcBdvLiKKfC605wFdynbEgKs0fChV^M
				k9HYDhmJ8hX6+PaquiHJSVNhsv5tOshZkCfMBbyxwrKd8yZ5G5I+2gE9PUznxJaM^M
				HTmlOqm4HwFxzy0RRQIDAQAB
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.auth_token.authmgrinstname$ value=raCertAuth
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.auth_token.uid$ value=KRA-server.example.com-8443
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.auth_token.userid$ value=KRA-server.example.com-8443
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.requestor_name$ value=
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.profileid$ value=caUserCert
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.auth_token.userdn$ value=uid=KRA-server.example.com-4747,ou=People,dc=example,dc=com
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.requestid$ value=20
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.auth_token.authtime$ value=1212782378071
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.req_x509info$ value=MIICIKADAgECAgEAMA0GCSqGSIb3DQEBBQUAMEAxHjAcBgNVBAoTFVJlZGJ1ZGNv^M
				bXB1dGVyIERvbWFpbjEeMBwGA1UEAxMVQ2VydGlmaWNhdGUgQXV0aG9yaXR5MB4X^M
				DTA4MDYwNjE5NTkzOFoXDTA4MTIwMzE5NTkzOFowOzEhMB8GCSqGSIb3DQEJARYS^M
				anNtaXRoQGV4YW1wbGUuY29tMRYwFAYKCZImiZPyLGQBARMGanNtaXRoMIGfMA0G^M
				CSqGSIb3DQEBAQUAA4GNADCBiQKBgQDreuEsBWq9WuZ2MaBwtNYxvkLPHcN0cusY^M
				7gxLzB+XwQ/VsWEoObGldg6WwJPOcBdvLiKKfC605wFdynbEgKs0fChVk9HYDhmJ^M
				8hX6+PaquiHJSVNhsv5tOshZkCfMBbyxwrKd8yZ5G5I+2gE9PUznxJaMHTmlOqm4^M
				HwFxzy0RRQIDAQABo4HFMIHCMB8GA1UdIwQYMBaAFG8gWeOJIMt+aO8VuQTMzPBU^M
				78k8MEoGCCsGAQUFBwEBBD4wPDA6BggrBgEFBQcwAYYuaHR0cDovL3Rlc3Q0LnJl^M
				ZGJ1ZGNvbXB1dGVyLmxvY2FsOjkwODAvY2Evb2NzcDAOBgNVHQ8BAf8EBAMCBeAw^M
				HQYDVR0lBBYwFAYIKwYBBQUHAwIGCCsGAQUFBwMEMCQGA1UdEQQdMBuBGSRyZXF1^M
				ZXN0LnJlcXVlc3Rvcl9lbWFpbCQ=

				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.profileapprovedby$ value=admin
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.cert_request$ value=MIIBozCCAZ8wggEFAgQqTfoHMIHHgAECpQ4wDDEKMAgGA1UEAxMBeKaBnzANBgkqhkiG9w0BAQEFAAOB...
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.profile$ value=true
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.cert_request_type$ value=crmf
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.requestversion$ value=1.0.0
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.req_locale$ value=en
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.requestowner$ value=KRA-server.example.com-8443
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.dbstatus$ value=NOT_UPDATED
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.subject$ value=uid=jsmith, e=jsmith@example.com
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.requeststatus$ value=begin
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.auth_token.user$ value=uid=KRA-server.example.com-8443,ou=People,dc=example,dc=com
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.req_key$ value=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDreuEsBWq9WuZ2MaBwtNYxvkLP^M
				HcN0cusY7gxLzB+XwQ/VsWEoObGldg6WwJPOcBdvLiKKfC605wFdynbEgKs0fChV^M
				k9HYDhmJ8hX6+PaquiHJSVNhsv5tOshZkCfMBbyxwrKd8yZ5G5I+2gE9PUznxJaM^M
				HTmlOqm4HwFxzy0RRQIDAQAB
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.auth_token.authmgrinstname$ value=raCertAuth
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.auth_token.uid$ value=KRA-server.example.com-8443
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.auth_token.userid$ value=KRA-server.example.com-8443
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.requestor_name$ value=
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.profileid$ value=caUserCert
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.auth_token.userdn$ value=uid=KRA-server.example.com-4747,ou=People,dc=example,dc=com
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.requestid$ value=20
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.auth_token.authtime$ value=1212782378071
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.req_x509info$ value=MIICIKADAgECAgEAMA0GCSqGSIb3DQEBBQUAMEAxHjAcBgNVBAoTFVJlZGJ1ZGNv^M
				bXB1dGVyIERvbWFpbjEeMBwGA1UEAxMVQ2VydGlmaWNhdGUgQXV0aG9yaXR5MB4X^M
				DTA4MDYwNjE5NTkzOFoXDTA4MTIwMzE5NTkzOFowOzEhMB8GCSqGSIb3DQEJARYS^M
				anNtaXRoQGV4YW1wbGUuY29tMRYwFAYKCZImiZPyLGQBARMGanNtaXRoMIGfMA0G^M
				CSqGSIb3DQEBAQUAA4GNADCBiQKBgQDreuEsBWq9WuZ2MaBwtNYxvkLPHcN0cusY^M
				7gxLzB+XwQ/VsWEoObGldg6WwJPOcBdvLiKKfC605wFdynbEgKs0fChVk9HYDhmJ^M
				8hX6+PaquiHJSVNhsv5tOshZkCfMBbyxwrKd8yZ5G5I+2gE9PUznxJaMHTmlOqm4^M
				HwFxzy0RRQIDAQABo4HFMIHCMB8GA1UdIwQYMBaAFG8gWeOJIMt+aO8VuQTMzPBU^M
				78k8MEoGCCsGAQUFBwEBBD4wPDA6BggrBgEFBQcwAYYuaHR0cDovL3Rlc3Q0LnJl^M
				ZGJ1ZGNvbXB1dGVyLmxvY2FsOjkwODAvY2Evb2NzcDAOBgNVHQ8BAf8EBAMCBeAw^M
				HQYDVR0lBBYwFAYIKwYBBQUHAwIGCCsGAQUFBwMEMCQGA1UdEQQdMBuBGSRyZXF1^M
				ZXN0LnJlcXVlc3Rvcl9lbWFpbCQ=

Likewise, the OCSP shows OCSP request information:

{YY-MM-DD}[http-11180-Processor25]: OCSPServlet: OCSP Request:
{YY-MM-DD}[http-11180-Processor25]{LogLevel}: OCSPServlet:
MEUwQwIBADA+MDwwOjAJBgUrDgMCGgUABBSEWjCarLE6/BiSiENSsV9kHjqB3QQU

{YY-MM-DD}[http-11180-Processor25]: OCSPServlet: OCSP Request:
{YY-MM-DD}[http-11180-Processor25]{LogLevel}: OCSPServlet:
MEUwQwIBADA+MDwwOjAJBgUrDgMCGgUABBSEWjCarLE6/BiSiENSsV9kHjqB3QQU

All subsystems keep an install log.

Every time a subsystem is created either through the initial installation or creating additional instances with pkispawn, an installation file with the complete debug output from the installation, including any errors and, if the installation is successful, the URL and PIN to the configuration interface for the instance. The file is created in the /var/log/pki/ directory for the instance with a name in the form pki-subsystem_name-spawn.timestamp.log.

Each line in the install log follows a step in the installation process.

    ==========================================================================
                                INSTALLATION SUMMARY
    ==========================================================================

      Administrator's username:             caadmin
      Administrator's PKCS #12 file:
            /root/.dogtag/pki-tomcat/ca_admin_cert.p12

      Administrator's certificate nickname:
            caadmin
      Administrator's certificate database:
            /root/.dogtag/pki-tomcat/ca/alias

      To check the status of the subsystem:
            systemctl status pki-tomcatd@pki-tomcat.service

      To restart the subsystem:
            systemctl restart pki-tomcatd@pki-tomcat.service

      The URL for the subsystem is:
            https://localhost.localdomain:8443/ca

      PKI instances will be enabled upon system boot

    ==========================================================================

    ==========================================================================
                                INSTALLATION SUMMARY
    ==========================================================================

      Administrator's username:             caadmin
      Administrator's PKCS #12 file:
            /root/.dogtag/pki-tomcat/ca_admin_cert.p12

      Administrator's certificate nickname:
            caadmin
      Administrator's certificate database:
            /root/.dogtag/pki-tomcat/ca/alias

      To check the status of the subsystem:
            systemctl status pki-tomcatd@pki-tomcat.service

      To restart the subsystem:
            systemctl restart pki-tomcatd@pki-tomcat.service

      The URL for the subsystem is:
            https://localhost.localdomain:8443/ca

      PKI instances will be enabled upon system boot

    ==========================================================================

The CA, KRA, OCSP, TKS, and TPS subsystems use a Tomcat web server instance for their agent and end-entities' interfaces.

Error and access logs are created by the Tomcat web server, which are installed with the Certificate System and provide HTTP services. The error log contains the HTTP error messages the server has encountered. The access log lists access activity through the HTTP interface.

Logs created by Tomcat:

These logs are not available or configurable within the Certificate System; they are only configurable within Apache or Tomcat. See the Apache documentation for information about configuring these logs.

The self-tests log records information obtained during the self-tests run when the server starts or when the self-tests are manually run. The tests can be viewed by opening this log. This log is not configurable through the Console. This log can only be configured by changing settings in the CS.cfg file. The information about logs in this section does not pertain to this log. See Section 2.3.13, “Self-tests” for more information about self-tests.

When starting a Certificate System instance, there is a short period of time before the logging subsystem is set up and enabled. During this time, log contents are written to standard out, which is captured by systemd and exposed via the journalctl utility.

To view these logs, run the following command:

journalctl -u pki-tomcatd@instance_name.service

# journalctl -u pki-tomcatd@instance_name.service

OR if using the Nuxwdog watchdog:

journalctl -u pki-tomcatd-nuxwdog@instance_name.service

# journalctl -u pki-tomcatd-nuxwdog@instance_name.service

Often it is helpful to watch these logs as the instance is starting (for example, in the event of a self-test failure on startup). To do this, run these commands in a separate console prior to starting the instance:

journalctl -f -u pki-tomcatd@instance_name.service

# journalctl -f -u pki-tomcatd@instance_name.service

OR if using the Nuxwdog watchdog:

journalctl -f -u pki-tomcatd-nuxwdog@instance_name.service

# journalctl -f -u pki-tomcatd-nuxwdog@instance_name.service

Certificate System servers are Tomcat instances which consist of one or more Certificate System subsystems. Certificate System subsystems are web applications that provide specific type of PKI functions. General, shared subsystem information is contained in non-relocatable, RPM-defined shared libraries, Java archive files, binaries, and templates. These are stored in a fixed location.

The directories are instance specific, tied to the instance name. In these examples, the instance name is pki-tomcat; the true value is whatever is specified at the time the subsystem is created with pkispawn.

The directories contain customized configuration files and templates, profiles, certificate databases, and other files for the subsystem.

The directories are instance specific, tied to the instance name. In these examples, the instance name is pki-tomcat; the true value is whatever is specified at the time the subsystem is created with pkispawn.

The directories are instance specific, tied to the instance name. In these examples, the instance name is pki-tomcat; the true value is whatever is specified at the time the subsystem is created with pkispawn.

The directories are instance specific, tied to the instance name. In these examples, the instance name is pki-tomcat; the true value is whatever is specified at the time the subsystem is created with pkispawn.

The directories are instance specific, tied to the instance name. In these examples, the instance name is pki-tomcat; the true value is whatever is specified at the time the subsystem is created with pkispawn.

The directories are instance specific, tied to the instance name. In these examples, the instance name is pki-tomcat; the true value is whatever is specified at the time the subsystem is created with pkispawn.

There are some directories used by or common to all Certificate System subsystem instances for general server operations, listed in Table 2.8, “Subsystem file locations”.

An end entity enrolls in the PKI environment by submitting an enrollment request through the end-entity interface. There can be many kinds of enrollment that use different enrollment methods or require different authentication methods. Different interfaces can also accept different types of Certificate Signing Requests (CSR).

The Certificate Manager supports different ways to submit CSRs, such as using the graphical interface and command-line tools.

servlet=/ca/ee/ca/profileSubmitCMCSimple?profileId=caECSimpleCMCUserCert

servlet=/ca/ee/ca/profileSubmitCMCSimple?profileId=caECSimpleCMCUserCert

The Certificate System uses certificate profiles to configure the content of the certificate, the constraints for issuing the certificate, the enrollment method used, and the input and output forms for that enrollment. A single certificate profile is associated with issuing a particular type of certificate.

A set of certificate profiles is included for the most common certificate types; the profile settings can be modified. Certificate profiles are configured by an administrator, and then sent to the agent services page for agent approval. Once a certificate profile is approved, it is enabled for use. In case of a UI-enrollment, a dynamically-generated HTML form for the certificate profile is used in the end-entities page for certificate enrollment, which calls on the certificate profile. In case of a command line-based enrollment, the certificate profile is called upon to perform the same processing, such as authentication, authorization, input, output, defaults, and constraints. The server verifies that the defaults and constraints set in the certificate profile are met before acting on the request and uses the certificate profile to determine the content of the issued certificate.

The Certificate Manager can issue certificates with any of the following characteristics, depending on the configuration in the profiles and the submitted certificate request:

By default, the certificate enrollment profiles are stored in <instance directory>/ca/profiles/ca with names in the format of <profile id>.cfg. LDAP-based profiles are possible with proper pkispawn configuration parameters.

Certificate System provides authentication options for certificate enrollment. These include agent-approved enrollment, in which an agent processes the request, and automated enrollment, in which an authentication method is used to authenticate the end entity and then the CA automatically issues a certificate. CMC enrollment is also supported, which automatically processes a request approved by an agent.

It is possible to create a trusted relationship between two separate CAs by issuing and storing cross-signed certificates between these two CAs. By using cross-signed certificate pairs, certificates issued outside the organization’s PKI can be trusted within the system.

Users can revoke their certificates using:

There are two types of key archival mechanisms provided by KRA:

The KRA automatically archives private encryption keys if archiving is configured.

The KRA stores private encryption keys in a secure key repository; each key is encrypted and stored as a key record and is given a unique key identifier.

The archived copy of the key remains wrapped with the KRA’s storage key. It can be decrypted, or unwrapped, only by using the corresponding private key pair of the storage certificate. A combination of one or more key recovery (or KRA) agents' certificates authorizes the KRA to complete the key recovery to retrieve its private storage key and use it to decrypt/recover an archived private key. See Section 12.3.1, “Configuring agent-approved key recovery in the command line”.

The KRA indexes stored keys by key number, owner name, and a hash of the public key, allowing for highly efficient searching. The key recovery agents have the privilege to insert, delete, and search for key records.

When a Certificate Manager receives a certificate request that contains the key archival option, it automatically forwards the request to the KRA to archive the encryption key. The private key is encrypted by the transport key, and the KRA receives the encrypted copy and stores the key in its key repository. To archive the key, the KRA uses two special key pairs:

Figure 2.2, “How the Key Archival Process works in client-side key generation” illustrates how the key archival process occurs when an end entity requests a certificate in the case of client-side key generation.

Figure 2.2. How the Key Archival Process works in client-side key generation

View larger image

The KRA supports agent-initiated key recovery. Agent-initiated recovery is when designated recovery agents use the key recovery form on the KRA agent services portal to process and approve key recovery requests. With the approval of a specified number of agents, an organization can recover keys when the key’s owner is unavailable or when keys have been lost.

Through the KRA agent services portal, key recovery agents can collectively authorize and retrieve private encryption keys and associated certificates into a PKCS #12 package, which can then be imported into the client.

In key recovery authorization, one of the key recovery agents informs all required recovery agents about an impending key recovery. All recovery agents access the KRA key recovery portal. One of the agents initiates the key recovery process. The KRA returns a notification to the agent includes a recovery authorization reference number identifying the particular key recovery request that the agent is required to authorize. Each agent uses the reference number and authorizes key recovery separately.

KRA supports Asynchronous recovery, meaning that each step of the recovery process — the initial request and each subsequent approval or rejection — is stored in the KRA’s internal LDAP database, under the key entry. The status data for the recovery process can be retrieved even if the original browser session is closed or the KRA is shut down. Agents can search for the key to recover, without using a reference number.

This asynchronous recovery option is illustrated in Figure 2.3, “Asynchronous recovery”.

Figure 2.3. Asynchronous recovery

View larger image

The KRA informs the agent who initiated the key recovery process of the status of the authorizations.

When all of the authorizations are entered, the KRA checks the information. If the information presented is correct, it retrieves the requested key and returns it along with the corresponding certificate in the form of a PKCS #12 package to the agent who initiated the key recovery process.

The key recovery agent scheme configures the KRA to recognize to which group the key recovery agents belong and specifies how many of these recovery agents are required to authorize a key recovery request before the archived key is restored.

Apart from storing asymmetric keys, KRA can also store symmetric keys or secrets similar to symmetric keys, such as volume encryption secrets, or even passwords and passphrases. The pki utility supports options that enable storing and retrieving these other types of secrets.

KRA transport rotation allows for seamless transition between CA and KRA subsystem instances using a current and a new transport key. This allows KRA transport keys to be periodically rotated for enhanced security by allowing both old and new transport keys to operate during the time of the transition; individual subsystem instances take turns being configured while other clones continue to serve with no downtime.

In the KRA transport key rotation process, a new transport key pair is generated, a certificate request is submitted, and a new transport certificate is retrieved. The new transport key pair and certificate have to be included in the KRA configuration to provide support for the second transport key. Once KRA supports two transport keys, administrators can start transitioning CAs to the new transport key. KRA support for the old transport key can be removed once all CAs are moved to the new transport key.

To configure KRA transport key rotation:

After this, the rotation of KRA transport certificates is complete, and all the affected CAs and KRAs use the new KRA certificate only. For more information on how to perform the above steps, see the procedures below.

The TKS supports multiple smart card key sets. Each smart card vendor creates different default (developer) static key sets for their smart card token stocks, and the TKS is equipped with the static key set (per manufacturer) to kickstart the format process of a blank token.

During the format process of a blank smart card token, a Java applet and the uniquely derived symmetric key set are injected into the token. Each master key (in some cases referred to as keySet) that the TKS supports is to have a set of entries in the TKS configuration file (CS.cfg). Each TPS profile contains a configuration to direct its enrollment to the proper TKS keySet for the matching key derivation process that would essentially be responsible for establishing the Secure Channel secured by a set of session-specific keys between TMS and the smart card token.

On TKS, master keys are defined by named keySets for references by TPS. On TPS, depending on the enrollment type (internal or external registration), The keySet is either specified in the TPS profile, or determined by the keySet Mapping Resolver.

A Key Ceremony is a process for transporting highly sensitive keys in a secure way from one location to another. In one scenario, in a highly secure deployment environment, the master key can be generated in a secure vault with no network to the outside. Alternatively, an organization might want to have TKS and TPS instances on different physical machines. In either case, under the assumption that no one single person is to be trusted with the key, Red Hat Certificate System TMS provides a utility called tkstool to manage the secure key transportation.

When Global Platform-compliant smart cards are created at the factory, the manufacturer will burn a set of default symmetric keys onto the token. The TKS is initially configured to use these symmetric keys (one KeySet entry per vendor in the TKS configuration). However, since these symmetric keys are not unique to the smart cards from the same stock, and because these are well-known keys, it is strongly encouraged to replace these symmetric keys with a set that is unique per token, not shared by the manufacturer, to restrict the set of entities that can manipulate the token.

The changing over of the keys takes place with the assistance of the Token Key Service subsystem. One of the functions of the TKS is to oversee the Master Keys from which the previously discussed smart card token keys are derived. There can be more than one master key residing under the control of the TKS.

The Red Hat Certificate System Token Management System (TMS) supports the GlobalPlatform smart card specification, in which the Secure Channel implementation is done with the Token Key System (TKS) managing the master key and the Token Processing System (TPS) communicating with the smart card (tokens) with Application Protocol Data Units (APDUs).

There are two types of APDUs:

The initiation of the APDU commands may be triggered when clients take action and connect to the Certificate System server for requests. A secure channel begins with an InitializeUpdate APDU sent from TPS to the smart card token, and is fully established with the ExternalAuthenticate APDU. Then, both the token and TMS would have established a set of shared secrets, called session keys, which are used to encrypt and authenticate the communication. This authenticated and encrypted communication channel is called Secure Channel.

Because TKS is the only entity that has access to the master key which is capable of deriving the set of unique symmetric on-token smart card keys, the Secure Channel provides the adequately safeguarded communication between TMS and each individual token. Any disconnection of the channel will require reestablishment of new session keys for a new channel.

Red Hat Certificate System includes the Coolkey Java applet, written specifically to run on TMS-supported smart card tokens. The Coolkey applet connects to a PKCS#11 module that handles the certificate and key related operations. During a token format operation, this applet is injected onto the smart card token using the Secure Channel protocol, and can be updated per configuration.

The TPS in Red Hat Certificate System is available to provision smart cards on the behalf of end users of the smart cards. The Token Processing System provides support for the following major token operations:

The following other operations can be considered supplementary or inherent operations to the main ones listed above. They can be triggered per relevant configuration or by the state of the token.

The Certificate System Token Processing System subsystem facilitates the management of smart card tokens. Tokens are provisioned by the TPS such that they are taken from a blank state to either a Formatted or Enrolled condition. A Formatted token is one that contains the CoolKey applet supported by TPS, while an Enrolled token is personalized (a process called binding) to an individual with the requisite certificates and cryptographic keys. This fully provisioned token is ready to use for crytptographic operations.

The TPS can also manage Profiles. The notion of a token Profile is related to:

The following list contains some of the quantities that make up a unique token profile:

These above and many others can be configured for each token type or profile. A full list of available configuration options is available in the Red Hat Certificate System Administration Guide.

Another question to consider is how a given token being provisioned by a user will be mapped to an individual token profile. There are two types of registration:

The registration to be used is configured globally per TPS instance.

The Token Processing System makes use of the LDAP token database store, which is used to keep a list of active tokens and their respective certificates, and to keep track of the current state of each token. A brand new token is considered Uninitialized, while a fully enrolled token is Enrolled. This data store is constantly updated and consulted by the TPS when processing tokens.

tokendb.allowedTransitions=0:1,0:2,0:3,0:6,3:2,3:6,4:1,4:2,4:3,4:6,6:7

tokendb.allowedTransitions=0:1,0:2,0:3,0:6,3:2,3:6,4:1,4:2,4:3,4:6,6:7

tps.operations.allowedTransitions=0:0,0:4,4:4,4:0,7:0

tps.operations.allowedTransitions=0:0,0:4,4:4,4:0,7:0

Token states
Token state transitions

# Token states
UNFORMATTED         = Unformatted
FORMATTED           = Formatted (uninitialized)
ACTIVE              = Active
SUSPENDED           = Suspended (temporarily lost)
PERM_LOST           = Permanently lost
DAMAGED             = Physically damaged
TEMP_LOST_PERM_LOST = Temporarily lost then permanently lost
TERMINATED          = Terminated

# Token state transitions
FORMATTED.DAMAGED        = This token has been physically damaged.
FORMATTED.PERM_LOST      = This token has been permanently lost.
FORMATTED.SUSPENDED      = This token has been suspended (temporarily lost).
FORMATTED.TERMINATED     = This token has been terminated.
SUSPENDED.ACTIVE         = This suspended (temporarily lost) token has been found.
SUSPENDED.PERM_LOST      = This suspended (temporarily lost) token has become permanently lost.
SUSPENDED.TERMINATED     = This suspended (temporarily lost) token has been terminated.
SUSPENDED.FORMATTED      = This suspended (temporarily lost) token has been found.
ACTIVE.DAMAGED           = This token has been physically damaged.
ACTIVE.PERM_LOST         = This token has been permanently lost.
ACTIVE.SUSPENDED         = This token has been suspended (temporarily lost).
ACTIVE.TERMINATED        = This token has been terminated.
TERMINATED.UNFORMATTED   = Reuse this token.

RE_ENROLL=YES;RENEW=NO;FORCE_FORMAT=NO;PIN_RESET=NO;RESET_PIN_RESET_TO_NO=NO;RENEW_KEEP_OLD_ENC_CERTS=YES

RE_ENROLL=YES;RENEW=NO;FORCE_FORMAT=NO;PIN_RESET=NO;RESET_PIN_RESET_TO_NO=NO;RENEW_KEEP_OLD_ENC_CERTS=YES

The Mapping Resolver is an extensible mechanism used by the TPS to determine which token profile to assign to a specific token based on configurable criteria. Each mapping resolver instance can be uniquely defined in the configuration, and each operation can point to various defined mapping resolver instance.

FilterMappingResolver is the only mapping resolver implementation provided with the TPS by default. It allows you to define a set of mappings and a target result for each mapping. Each mapping contains a set of filters, where:

The input filter parameters are information received from the smart card token with or without extensions. They are run against the FilterMappingResolver according to the above rules. The following input filter parameters are supported by FilterMappingResolver:

The TPS supports the following roles by default:

The Certificate System is configured by default with three user types with different access levels to the system:

Additionally, when a security domain is created, the CA subsystem which hosts the domain is automatically granted the special role of Security Domain Administrator, which gives the subsystem the ability to manage the security domain and the subsystem instances within it. Other security domain administrator roles can be created for the different subsystem instances. These special roles should not have actual users as members.