2.3. Certificate System Architecture Overview

Although each provides a different service, all RHCS subsystems (CA, KRA, OCSP, TKS, TPS) share a common architecture. The following architectural diagram shows the common architecture shared by all of these subsystems.

2.3.1. Java Application Server

Java application server is a Java framework to run server applications. The Certificate System is designed to run within a Java application server. Currently the only Java application server supported is Tomcat 8. Support for other application servers may be added in the future. More information can be found at http://tomcat.apache.org/.
Each Certificate System instance is a Tomcat server instance. The Tomcat configuration is stored in server.xml. The following link provides more information about Tomcat configuration: https://tomcat.apache.org/tomcat-8.0-doc/config/.
Each Certificate System subsystem (such as CA or KRA) is deployed as a web application in Tomcat. The web application configuration is stored in a web.xml file, which is defined in Java Servlet 3.1 specification. See https://www.jcp.org/en/jsr/detail?id=340 for details.
The Certificate System configuration itself is stored in CS.cfg.
See Section 2.3.14, “Instance Layout” for the actual locations of these files.

2.3.2. Java Security Manager

Java services have the option of having a Security Manager which defines unsafe and safe operations for applications to perform. When the subsystems are installed, they have the Security Manager enabled automatically, meaning each Tomcat instance starts with the Security Manager running.
The Security Manager is disabled if the instance is created by running pkispawn and using an override configuration file which specifies the pki_security_manager=false option under its own Tomcat section.
The Security Manager can be disabled from an installed instance using the following procedure:
  1. # systemctl stop pki-tomcatd@instance_name.service
    or
    # systemctl stop pki-tomcatd-nuxwdog@instance_name.service
    (if using the nuxwdog watchdog)
  2. Open the /etc/sysconfig/instance_name file, and set SECURITY_MANAGER="false"
  3. # systemctl start pki-tomcatd@instance_name.service
    or
    # systemctl start pki-tomcatd-nuxwdog@instance_name.service
    (if using the nuxwdog watchdog)
When an instance is started or restarted, a Java security policy is constructed or reconstructed by pkidaemon from the following files:
/usr/share/pki/server/conf/catalina.policy
/usr/share/tomcat/conf/catalina.policy
/var/lib/pki/$PKI_INSTANCE_NAME/conf/pki.policy
/var/lib/pki/$PKI_INSTANCE_NAME/conf/custom.policy
Then, it is saved into /var/lib/pki/instance_name/conf/catalina.policy.

2.3.3. Interfaces

2.3.3.1. Servlet Interface

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.

2.3.3.2. Administrative Interface

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.

2.3.3.3. End-Entity Interface

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.

2.3.3.4. Operator Interface

The operator interface is only found in the TPS subsystem.

2.3.4. REST Interface

Representational state transfer (REST) is a way to use HTTP to define and organize web services which will simplify interoperability with other applications. Red Hat Certificate System provides a REST interface to access various services on the server.
The REST services in Red Hat Certificate System are implemented using the RESTEasy framework. RESTEasy is actually running as a servlet in the web application, so the RESTEasy configuration can also be found in the web.xml of the corresponding subsystem. More information about RESTEasy can be found at http://resteasy.jboss.org/.
Each REST service is defined as a separate URL. For example:
  • CA certificate service: http://<host_name>:<port>/ca/rest/certs/
  • KRA key service: http://<host_name>:<port>/kra/rest/agent/keys/
  • TKS user service: http://<host_name>:<port>/tks/rest/admin/users/
  • TPS group service: http://<host_name>:<port>/tps/rest/admin/groups/
Some services can be accessed using plain HTTP connection, but some others may require HTTPS connection for security.
The REST operation is specified as HTTP method (for example, GET, PUT, POST, DELETE). For example, to get the CA users the client will send a GET /ca/rest/users request.
The REST request and response messages can be sent in XML or JSON format. For example:
{
	"id":"admin",
	"UserID":"admin",
	"FullName":"Administrator",
	"Email":"admin@example.com",
	...
}
The REST interface can be accessed using tools such as CLI, Web UI, or generic REST client. Certificate System also provides Java, Python, and JavaScript libraries to access the services programmatically.
The REST interface supports two types of authentication methods:
  • user name and password
  • client certificate
The authentication method required by each service is defined in /usr/share/pki/ca/conf/auth-method.properties.
The REST interface may require certain permissions to access the service. The permissions are defined in the ACL resources in LDAP. The REST interface are mapped to the ACL resources in the /usr/share/pki/<subsystem>/conf/acl.properties.
For more information about the REST interface, see http://www.dogtagpki.org/wiki/REST.

2.3.5. JSS

Java Security Services (JSS) provides a Java interface for security operations performed by NSS. JSS and higher levels of the Certificate System architecture are built with Java Native Interface (JNI), which provides binary compatibility across different versions of the Java Virtual Machine (JVM). This design allows customized subsystem services to be compiled and built just once and run on a range of platforms. JSS supports most of the security standards and encryption technologies supported by NSS. JSS also provides a pure Java interface for ASN.1 types and BER-DER encoding.

2.3.6. Tomcatjss

Java-based subsystems in Red Hat Certificate System use a single JAR file called tomcatjss as a bridge between the Tomcat Server HTTP engine and JSS, the Java interface for security operations performed by NSS. Tomcatjss is a Java Secure Socket Extension (JSSE) implementation using Java Security Services (JSS) for Tomcat.
The following configuration in the server.xml file found in the pki-tomcat/conf directory can be used to explain how Tomcatjss fits into the entire Certificate System ecosystem. Portions of the Connector entry for the secret port are shown below.
<Connector name="Secure"

# Info about the socket itself
	port="8443"
	protocol="org.apache.coyote.http11.Http11Protocol"
	SSLEnabled="true"
	sslProtocol="SSL"
	scheme="https"
	secure="true"
	connectionTimeout="80000"
	maxHttpHeaderSize="8192"
	acceptCount="100" maxThreads="150" minSpareThreads="25"
	enableLookups="false" disableUploadTimeout="true"
	#Points to our tomcat jss implementation
	sslImplementationName="org.apache.tomcat.util.net.jss.JSSImplementation"
	enableOCSP="false"

#Optional ocsp responder configuration can be enabled here
	ocspResponderURL="http://server.example.com.com:9080/ca/ocsp"
	ocspResponderCertNickname="ocspSigningCert cert-pki-ca"
	ocspCacheSize="1000"
	ocspMinCacheEntryDuration="60"
	ocspMaxCacheEntryDuration="120"
	ocspTimeout="10"
	strictCiphers="true"
	#This configures the client auth scheme we want for this server socket. Want means that the client auth cert is optional. We could also have made it “required” to give no choice.
	clientAuth="want"

# A collection of cipher related settings that make sure connections are secure.
	sslOptions="ssl2=false,ssl3=false,tls=true"
	ssl3Ciphers="-SSL3_FORTEZZA_ ..."
	tlsCiphers="-TLS_ECDH_ECDSA_WITH_AES_128_"
	sslVersionRangeStream="tls1_0:tls1_2"
	sslVersionRangeDatagram="tls1_1:tls1_2"
	sslRangeCiphers="-TLS_ECDH_ECDSA_W"
	serverCertNickFile="/var/lib/pki/pki-tomcat/conf/serverCertNick.conf"
	passwordFile="/var/lib/pki/pki-tomcat/conf/password.conf"
	passwordClass="org.apache.tomcat.util.net.jss.PlainPasswordFile"
	certdbDir="/var/lib/pki/pki-tomcat/alias"
/>
Note that this Connector contains the pointer to the tomcatjss implementation, which can be plugged into the sslImplementation property of this Connector object.
Tomcatjss implements the interfaces needed to use SSL and to create SSL sockets. The socket factory, which tomcatjss implements, makes use of the various properties listed below to create an SSL server listening socket and return it to tomcat. Tomcatjss itself, makes use of our java JSS system to ultimately communicate with the native NSS cryptographic services on the machine.
Tomcatjss is loaded when the Tomcat server and the Certificate System classes are loaded. The load process is described below:
  1. The server is started.
  2. Tomcat gets to the point where it needs to create the listening sockets for the Certificate System installation.
  3. The server.xml file is processed. Configuration in this file tells the system to use a socket factory implemented by Tomcatjss.
  4. For each requested socket, Tomcajss reads and processes the included attributes when it creates the socket. The resulting socket will behave as it has been asked to by those parameters.
  5. Once the server is running, we have the required set of listening sockets waiting for incoming connections to the Tomcat-based Certificate System.
Note that when the sockets are created at startup, Tomcatjss is the first entity in Certificate System that actually deals with the underlying JSS security services. Once the first listening socket is processed, an instance of JSS is created for use going forward.

2.3.7. PKCS#11 Modules

Public-Key Cryptography Standard (PKCS) #11 specifies an API used to communicate with devices that hold cryptographic information and perform cryptographic operations. Because it supports PKCS #11, Certificate System works with a wide range of hardware and software devices intended for such purposes.
One or more PKCS #11 modules must be available to any Certificate System subsystem instance. A PKCS #11 module (also called a cryptographic module or cryptographic service provider) manages cryptographic services such as encryption and decryption using the PKCS #11 interface. PKCS #11 modules can be thought of as drivers for cryptographic devices that can be implemented in either hardware or software.
NSS provides a built-in PKCS #11 module that is used by Certificate System. Network Security Services (NSS) is a set of libraries designed to support cross-platform development of security-enabled communications applications. Applications built with the NSS libraries support the SSL protocol for authentication, tamper detection, and encryption as well as the PKCS #11 interface for cryptographic token interfaces. Red Hat uses NSS to support these features in a wide range of products, including Certificate System.
The NSS document can be found online at http://www.mozilla.org/projects/security/pki/nss/overview.html. NSS tools are frequently used to manage the PKI environment. For more information, see https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/tools.
A PKCS #11 module always has one or more slots, which can be implemented as physical hardware slots in some form of physical reader (for example, for smart cards) or as conceptual slots in software. Each slot for a PKCS #11 module can in turn contain a token, which is the hardware or software device that actually provides cryptographic services and optionally stores certificates and keys.

2.3.7.1. TLS Ciphers

Each PKI deployment may have policies on how it wishes its clients to communicate with the PKI servers. RHCS allows its TLS ciphers to be configured.
When acting as a TLS server, each Certificate  instance’s TLS cipher list can be configured from its server.xml file. When acting as a TLS client (for inter-subsystem communication), the instance’s TLS cipher list can be configured in the instance’s configuration file, CS.cfg.
See the Red Hat Certificate System Administration Guide for configuration information..

2.3.7.2. NSS Soft Token

NSS provides two built-in modules with Certificate System:
  • Default NSS Internal PKCS #11 Module. This comes with two built-in tokens:
    • The Internal Crypto Services token performs all cryptographic operations, such as encryption, decryption, and hashing.
    • The Internal Key Storage token handles all communication with the certificate and key database files (called certX.db and keyX.db, respectively, where X is a version number) that store certificates and keys.
  • FIPS 140-2 module. This module complies with the FIPS 140-2 government standard for implementations of cryptographic modules. Many products sold to the US government must comply with one or more of the FIPS standards. The FIPS 140-2 module includes a single, built-in FIPS 140-2 Certificate DB token , which handles both cryptographic operations and communication with the certX.db and keyX.db files.

2.3.7.3. HSMs

See the pkispawn man page for an example of setting up a PKI subsystem to utilize an HSM.
An external token refers to an external hardware device, such as a smart card or hardware security module (HSM), that the Certificate System uses to generate and store its key pairs and certificates. The Certificate System should work with most hardware tokens that are compliant with PKCS #11 but officially, Certificate System 9 only supports certain models of the Gemalto Safenet LunaSA and nCipher nShield HSMs.

Note

See your specific HSM vendor documentation for installation and configuration instructions for using the HSM.
PKCS #11 is a standard set of APIs and shared libraries which isolate an application from the details of the cryptographic device. This enables the application to provide a unified interface for PKCS #11-compliant cryptographic devices.
The PKCS #11 module provided by NSS in the Certificate System supports cryptographic devices supplied by many different manufacturers. This module allows the Certificate System to plug in shared libraries supplied by manufacturers of external encryption devices and use them for generating and storing keys and certificates for the Certificate System managers.
Consider using HSMs for generating and storing the key pairs and certificates used by Certificate System. These devices are another security measure to safeguard private keys because hardware tokens are in general considered more secure than software tokens.
Before using external tokens, plan how the external token is going to be used with the subsystem:
  • All system keys for a subsystem must be generated on the same token.
  • Preferably, the subsystem keys should be generated in an empty HSM slot. If the HSM slot has previously been used to store other keys, then use the HSM vendor's utilities to delete the contents of the slot. The Certificate System has to be able to create certificates and keys on the slot with default nicknames. If not properly cleaned up, the names of these objects may collide with previous instances.
  • A single HSM can be used to store certificates and keys for multiple subsystem instances, which may be installed on multiple hosts. When an HSM is used, any certificate nickname for a subsystem must be unique for every subsystem instance managed on the HSM.

Note

For KRA to perform wrapping and unwrapping on an HSM for key archival and recovery, the HSM must have the capability to wrap and unwrap private keys. If the HSM does not have this capability, the KRA has to be downgraded to be able to encrypt and decrypt user private keys for its key archival and recovery functionalities.

Important

If multiple subsystems share the same networked HSM, make sure the nicknames and certificate subject distinguished names are uniquely specified to avoid conflict.

2.3.7.4. Smart Cards (Clients)

Smart Cards are managed using the Enterprise Security Client, which is documented in a separate guide that describes its architecture, concepts, and provides information on installation, configuration, and administration. See Managing Smart Cards with the Enterprise Security Client.

2.3.8. Certificate System Serial Number Management

2.3.8.1. Serial Number Ranges

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:
  • Current serial number management is based on assigning ranges of sequential serial numbers.
  • Instances request new ranges when crossing below a defined threshold.
  • Instances store information about a newly acquired range once it is assigned to the instance.
  • Instances continue using old ranges until all numbers are exhausted from it, and then it moves to the new range.
  • Cloned subsystems synchronize their range assignment through replication conflicts.
For new clones:
  • Part of the current range of the master is transferred to a new clone in the process of cloning.
  • New clones may request a new range if the transferred range is below the defined threshold.
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

2.3.8.2. Random Serial Number Management

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
If selected, certificate request numbers and certificate serial numbers will be selected randomly within the specified ranges.

2.3.9. Security Domain

A security domain is a registry of PKI services. Services such as CAs register information about themselves in these domains so users of PKI services can find other services by inspecting the registry. The security domain service in RHCS manages both the registration of PKI services for Certificate System subsystems and a set of shared trust policies.

2.3.10. Passwords and Watchdog (nuxwdog)

In the default setup, an RHCS subsystem instance needs to act as a client and authenticate to some other services, such as an LDAP internal database (unless SSL client authentication is set up, where a certificate will be used for authentication instead), the NSS token database, or sometimes an HSM, with a password. The administrator is prompted to set up this password at the time of installation configuration. This password is then written to the file <instance_dir>/conf/password.conf. At the same time, an identifying string is stored in the main configuration file CS.cfg as part of the parameter cms.passwordlist.
The password entries in the password.conf file are in the following format:
<name>=<password>
E.g.
internal=413691159497
In cases where an HSM token is used, the following format is used:
hardware-<name>=<password>
E.g.
hardware-internal=413691159497
The configuration file, CS.cfg, is protected by Red Hat Enterprise Linux, and only accessible by the PKI administrators. No passwords are stored in CS.cfg.
During installation, the installer will select and log into either the internal software token or a hardware cryptographic token. The login passphrase to these tokens is also written to password.conf.
Configuration at a later time can also place passwords into password.conf. LDAP publishing is one example where the newly configured Directory Manager password for the publishing directory is entered into password.conf.
Nuxwdog is a lightweight auxiliary daemon process that is used to start, stop, monitor the status of, and reconfigure server programs. It is most useful when users need to be prompted for passwords to start a server, because it caches these passwords securely in the kernel keyring, so that restarts can be done automatically in the case of a server crash.
Once installation is complete, it is possible to remove the password.conf file altogether. On restart, the nuxwdog watchdog program will prompt the administrator for the required passwords, using the parameter cms.passwordlist as a list of passwords for which to prompt. The passwords are then cached by nuxwdog in the kernel keyring to allow automated recovery from a server crash. This automated recovery (automatic subsystem restart) happens in case of uncontrolled shutdown (crash). In case of a controlled shutdown by the administrator, administrators are prompted for passwords again.
When using the watchdog service, starting and stopping an RHCS instance are done differently. For details, see the corresponding section in the Certificate System Administration Guide.

2.3.11. Internal LDAP Database

Red Hat Certificate System employs Red Hat Directory Server (RHDS) as its internal database for storing information such as certificates, requests, users, roles, ACLs, as well as other miscellaneous internal information. Certificate System communicates with the internal LDAP database either with a password, or securely by means of SSL authentication.
If certificate-based authentication is required between a Certificate System instance and Directory  Server, it is important to follow instruction to set up trust between these two entities. Proper pkispawn options will also be needed for installing such Certificate System instance.
Red Hat Certificate System allows installation and configuration of a PKI instance to connect directly with a Directory Server instance that is running in Secure Lightweight Directory Access Protocol (LDAPS). The protocol must be enabled in the Directory Server.
To verify that a client can connect securely over LDAPS, use the following command:
# /usr/lib64/mozldap/ldapsearch -Z -h server.example.com -p 636 -D 'cn=Directory Manager' -w password -b "dc=example, dc=com" "objectclass=*"
Once you verify the connection, export the self-signed CA certificate using the following command:
# certutil -L -d /etc/dirsrv/slapd-pki -n "CA certificate" -a > $HOME/dscacert.pem
Then, add the following parameters into the [DEFAULT] section of the PKI instance override configuration file:
[DEFAULT]
pki_ds_secure_connection=True
pki_ds_secure_connection_ca_pem_file=$HOME/dscacert.pem
pki_ds_ldaps_port=636
Finally, execute the pkispawn command to create the PKI subsystem.
For more information, see the pkispawn man page.

2.3.12. Security-Enhanced Linux (SELinux)

SELinux is a collection of mandatory access control rules which are enforced across a system to restrict unauthorized access and tampering. SELinux is described in more detail in Red Hat Enterprise Linux 7 SELinux User's and Administrator's Guide.
Basically, SELinux identifies objects on a system, which can be files, directories, users, processes, sockets, or any other resource on a Linux host. These objects correspond to the Linux API objects. Each object is then mapped to a security context, which defines the type of object and how it is allowed to function on the Linux server.
Objects can be grouped into domains, and then each domain is assigned the proper rules. Each security context has rules which set restrictions on what operations it can perform, what resources it can access, and what permissions it has.
SELinux policies for the Certificate System are incorporated into the standard system SELinux policies. These SELinux policies apply to every subsystem and service used by Certificate System. By running Certificate System with SELinux in enforcing mode, the security of the information created and maintained by Certificate System is enhanced.
CA SELinux Port Policy

Figure 2.1. CA SELinux Port Policy

The Certificate System SELinux policies define the SELinux configuration for every subsystem instance:
  • Files and directories for each subsystem instance are labeled with a specific SELinux context.
  • The ports for each subsystem instance are labeled with a specific SELinux context.
  • All Certificate System processes are constrained within a subsystem-specific domain.
  • Each domain has specific rules that define what actions that are authorized for the domain.
  • Any access not specified in the SELinux policy is denied to the Certificate System instance.
For Certificate System, each subsystem is treated as an SELinux object, and each subsystem has unique rules assigned to it. The defined SELinux policies allow Certificate System objects run with SELinux set in enforcing mode.
Every time pkispawn is run to configure a Certificate System subsystem, files and ports associated with that subsystem are labeled with the required SELinux contexts. These contexts are removed when the particular subsystems are removed using pkidestroy.
The central definition in an SELinux policy is the pki_tomcat_t domain. Certificate System instances are Tomcat servers, and the pki_tomcat_t domain extends the policies for a standard tomcat_t Tomcat domain. All Certificate System instances on a server share the same domain.
When each Certificate System process is started, it initially runs in an unconfined domain (unconfined_t) and then transitions into the pki_tomcat_t domain. This process then has certain access permissions, such as write access to log files labeled pki_tomcat_log_t, read and write access to configuration files labeled pki_tomcat_etc_rw_t, or the ability to open and write to http_port_t ports.
The SELinux mode can be changed from enforcing to permissive, or even off, though this is not recommended.

2.3.13. Self-tests

Red Hat Certificate System provides a Self-Test framework which allows the PKI system integrity to be checked during startup or on demand or both. In the event of a non-critical self test failure, the message will be stored in the log file, while in the event of a critical self test failure, the message will be stored in the log file, while the Certificate System subsystem will properly shut down. The administrator is expected to watch the self-test log during the startup of the subsystem if they wish to see the self-test report during startup. They can also view the log after startup.
When a subsystem is shut down due to a self-test failure, it will also be automatically disabled. This is done to ensure that the subsystem does not partially run and produce misleading responses. Once the issue is resolved, the subsystem can be re-enabled by running the following command on the server:
# pki-server subsystem-enable <subsystem>

2.3.14. Instance Layout

Each Certificate System instance depends on a number of files. Some of them are located in instance-specific folders, while some others are located in a common folder which is shared with other server instances.
For example, the server configuration files are stored in /etc/pki/instance_name/server.xml, which is instance-specific, but the CA servlets are defined in /usr/share/pki/ca/webapps/ca/WEB-INF/web.xml, which is shared by all server instances on the system.

2.3.14.1. File and Directory Locations for Certificate System

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.

Table 2.2. Tomcat Instance Information

Setting Value
Main Directory /var/lib/pki/pki-tomcat
Configuration Directory /etc/pki/pki-tomcat
Configuration File
/etc/pki/pki-tomcat/server.xml
/etc/pki/pki-tomcat/password.conf
Security Databases /var/lib/pki/pki-tomcat/alias
Subsystem Certificates
SSL server certificate
Subsystem certificate [a]
Log Files /var/log/pki/pki-tomcat
Web Services Files
/usr/share/pki/server/webapps/ROOT - Main page
/usr/share/pki/server/webapps/pki/admin - Admin templates
/usr/share/pki/server/webapps/pki/js - JavaScript libraries
[a] The subsystem certificate is always issued by the security domain so that domain-level operations that require client authentication are based on this subsystem certificate.

Note

The /var/lib/pki/instance_name/conf/ directory is a symbolic link to the /etc/pki/instance_name/ directory.

2.3.14.2. CA Subsystem Information

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.

Table 2.3. CA Subsystem Information

Setting Value
Main Directory /var/lib/pki/pki-tomcat/ca
Configuration Directory /etc/pki/pki-tomcat/ca
Configuration File /etc/pki/pki-tomcat/ca/CS.cfg
Subsystem Certificates
CA signing certificate
OCSP signing certificate (for the CA's internal OCSP service)
Audit log signing certificate
Log Files /var/log/pki/pki-tomcat/ca
Install Logs /var/log/pki/pki-ca-spawn.YYYYMMDDhhmmss.log
Profile Files /var/lib/pki/pki-tomcat/ca/profiles/ca
Email Notification Templates /var/lib/pki/pki-tomcat/ca/emails
Web Services Files
/usr/share/pki/ca/webapps/ca/agent - Agent services
/usr/share/pki/ca/webapps/ca/admin - Admin services
/usr/share/pki/ca/webapps/ca/ee - End user services

2.3.14.3. KRA Subsystem Information

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.

Table 2.4. KRA Subsystem Information

Setting Value
Main Directory /var/lib/pki/pki-tomcat/kra
Configuration Directory /etc/pki/pki-tomcat/kra
Configuration File /etc/pki/pki-tomcat/kra/CS.cfg
Subsystem Certificates
Transport certificate
Storage certificate
Audit log signing certificate
Log Files /var/log/pki/pki-tomcat/kra
Install Logs /var/log/pki/pki-kra-spawn.YYYYMMDDhhmmss.log
Web Services Files
/usr/share/pki/kra/webapps/kra/agent - Agent services
/usr/share/pki/kra/webapps/kra/admin - Admin services

2.3.14.4. OCSP Subsystem Information

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.

Table 2.5. OCSP Subsystem Information

Setting Value
Main Directory /var/lib/pki/pki-tomcat/ocsp
Configuration Directory /etc/pki/pki-tomcat/ocsp
Configuration File /etc/pki/pki-tomcat/ocsp/CS.cfg
Subsystem Certificates
OCSP signing certificate
Audit log signing certificate
Log Files /var/log/pki/pki-tomcat/ocsp
Install Logs /var/log/pki/pki-ocsp-spawn.YYYYMMDDhhmmss.log
Web Services Files
/usr/share/pki/ocsp/webapps/ocsp/agent - Agent services
/usr/share/pki/ocsp/webapps/ocsp/admin - Admin services

2.3.14.5. TKS Subsystem Information

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.

Table 2.6. TKS Subsystem Information

Setting Value
Main Directory /var/lib/pki/pki-tomcat/tks
Configuration Directory /etc/pki/pki-tomcat/tks
Configuration File /etc/pki/pki-tomcat/tks/CS.cfg
Subsystem Certificates Audit log signing certificate
Log Files /var/log/pki/pki-tomcat/tks
Install Logs /var/log/pki/pki-tomcat/pki-tks-spawn.YYYYMMDDhhmmss.log

2.3.14.6. TPS Subsystem Information

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.

Table 2.7. TPS Subsystem Information

Setting Value
Main Directory /var/lib/pki/pki-tomcat/tps
Configuration Directory /etc/pki/pki-tomcat/tps
Configuration File /etc/pki/pki-tomcat/tps/CS.cfg
Subsystem Certificates Audit log signing certificate
Log Files /var/log/pki/pki-tomcat/tps
Install Logs /var/log/pki/pki-tps-spawn.YYYYMMDDhhhmmss.log
Web Services Files /usr/share/pki/tps/webapps/tps - TPS services

2.3.14.7. Shared Certificate System Subsystem File Locations

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

Table 2.8. Subsystem File Locations

Directory Location Contents
/usr/share/pki Contains common files and templates used to create Certificate System instances. Along with shared files for all subsystems, there are subsystem-specific files in subfolders:
  • pki/ca (CA)
  • pki/kra (KRA)
  • pki/ocsp (OCSP)
  • pki/tks (TKS)
  • pki/tps (TPS)
/usr/bin Contains the pkispawn and pkidestroy instance configuration scripts and tools (Java, native, and security) shared by the Certificate System subsystems.
/usr/share/java/pki Contains Java archive files shared by local Tomcat web applications and shared by the Certificate System subsystems.