Chapter 12. The Certificate System Configuration Files

The primary configuration file for every subsystem is its CS.cfg file. This chapter covers basic information about and rules for editing the CS.cfg file. This chapter also describes some other useful configuration files used by the subsystems, such as password and web services files.

12.1. File and Directory Locations for Certificate System Subsystems

Certificate System servers consist of an Apache Tomcat instance, which contains one or more subsystems. Each subsystem consists of a web application, which handles requests for a specific type of PKI function.
The available subsystems are: CA, KRA, OCSP, TKS, and TPS. Each instance can contain only one of each type of a PKI subsystem. See Section 13.1, “PKI Instances” for more information.
A subsystem can be installed within a particular instance using the pkispawn command.

12.1.1. Instance-specific Information

Server instances are located under the /var/lib/pki/instance_name/ directory. Each instance has ports and server-specific configuration under the /var/lib/pki/instance_name/conf/ directory. Note that the default instance name is pki-tomcat.

Table 12.1. Certificate Server Port Assignments (Default)

Port Type Port Number Notes
Secure port 8443 Main port used to access PKI services by end-users, agents, and admins over HTTPS.
Insecure port 8080 Used to access the server insecurely for some end-entity functions over HTTP. Used for instance to provide CRLs, which are already signed and therefore need not be encrypted.
AJP port 8009 Used to access the server from a front end Apache proxy server through an AJP connection. Redirects to the HTTPS port.
Tomcat port 8005 Used by the web server.

Table 12.2. Instance Information for the Default Instance (pki-tomcat)

Setting Value
Main directory /var/lib/pki/pki-tomcat/
Configuration directory /var/lib/pki-tomcat/conf/[a]
Server configuration files /var/lib/pki-tomcat/conf/server.xml
/var/lib/pki-tomcat/conf/password.conf
Security databases /var/lib/pki-tomcat/conf/alias/
Log files /var/lib/pki/pki-tomcat/logs/ [b]
Stdout logs Logs are now written to the journal;[c] to access the journal, run the following command: 
journalctl -u pki-tomcatd@pki-tomcat.service
Process file /var/run/pki-tomcat.pid
[a] This directory is usually linked to /etc/pki/pki-tomcat/
[b] This directory contains access log and is linked to /var/log/pki/pki-tomcat/
[c] Instances no longer write to the catalina.out file

12.1.2. CA Subsystem Information

This section contains details about the CA subsystem, which is one of the possible subsystems that can be installed as a web application in a Certificate Server instance.

Table 12.3. CA Subsystem Information for the Default Instance (pki-tomcat)

Setting Value
Main directory /var/lib/pki/pki-tomcat/ca/
Configuration directory /var/lib/pki/pki-tomcat/ca/conf/[a]
Configuration file /var/lib/pki/pki-tomcat/ca/conf/CS.cfg
Subsystem certificates CA signing certificate
OCSP signing certificate (for the CA's internal OCSP service)
SSL server certificate
Audit log signing certificate
Subsystem certificate[b]
Security databases /var/lib/pki/pki-tomcat/alias/[c]
Log files /var/lib/pki/pki-tomcat/ca/logs/[d]
Install log /var/log/pki/pki-ca-spawn.date.log
Unnstall log /var/log/pki/pki-ca-destroy.date.log
Audit logs /var/log/pki/pki-tomcat/ca/signedAudit/
Profile files /var/lib/pki/pki-tomcat/ca/profiles/ca/
Email notification templates /var/lib/pki/pki-tomcat/ca/emails/
Web services files Agent services: /var/lib/pki/pki-tomcat/ca/webapps/ca/agent/
Admin services: /var/lib/pki/pki-tomcat/ca/webapps/ca/admin/
End user services: /var/lib/pki/pki-tomcat/ca/webapps/ca/ee/
[a] Aliased to /etc/pki/pki-tomcat/ca/
[b] 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.
[c] Note that all subsystem certificates are stored in the instance security database
[d] Aliased to /var/log/pki/pki-tomcat/ca/

12.1.3. KRA Subsystem Information

This section contains details about the KRA subsystem, which is one of the possible subsystems that can be installed as a web application in a Certificate Server instance.

Table 12.4. KRA Subsystem Information for the Default Instance (pki-tomcat)

Setting Value
Main directory /var/lib/pki/pki-tomcat/kra/
Configuration directory /var/lib/pki/pki-tomcat/kra/conf/[a]
Configuration file /var/lib/pki/pki-tomcat/kra/conf/CS.cfg
Subsystem certificates Transport certificate
Storage certificate
SSL server certificate
Audit log signing certificate
Subsystem certificate[b]
Security databases /var/lib/pki/pki-tomcat/alias/[c]
Log files /var/lib/pki/pki-tomcat/kra/logs/
Install log /var/log/pki/pki-kra-spawn-date.log
Uninstall log /var/log/pki/pki-kra-destroy-date.log
Audit logs /var/log/pki/pki-tomcat/kra/signedAudit/
Web services files Agent services: /var/lib/pki/pki-tomcat/kra/webapps/kra/agent/
Admin services: /var/lib/pki/pki-tomcat/kra/webapps/kra/admin/
[a] Linked to /etc/pki/pki-tomcat/kra/
[b] 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.
[c] Note that all subsystem certificates are stored in the instance security database

12.1.4. OCSP Subsystem Information

This section contains details about the OCSP subsystem, which is one of the possible subsystems that can be installed as a web application in a Certificate Server instance.

Table 12.5. OCSP Subsystem Information for the Default Instance (pki-tomcat)

Setting Value
Main directory /var/lib/pki/pki-tomcat/ocsp/
Configuration directory /var/lib/pki/pki-tomcat/ocsp/conf/[a]
Configuration file /var/lib/pki/pki-tomcat/ocsp/conf/CS.cfg
Subsystem certificates Transport certificate
Storage certificate
SSL server certificate
Audit log signing certificate
Subsystem certificate[b]
Security databases /var/lib/pki/pki-tomcat/alias/[c]
Log files /var/lib/pki/pki-tomcat/ocsp/logs/
Install log /var/log/pki/pki-ocsp-spawn-date.log
Uninstall log /var/log/pki/pki-ocsp-destroy-date.log
Audit logs /var/log/pki/pki-tomcat/ocsp/signedAudit/
Web services files Agent services: /var/lib/pki/pki-tomcat/ocsp/webapps/ocsp/agent/
Admin services: /var/lib/pki/pki-tomcat/ocsp/webapps/ocsp/admin/
[a] Linked to /etc/pki/pki-tomcat/ocsp/
[b] 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.
[c] Note that all subsystem certificates are stored in the instance security database

12.1.5. TKS Subsystem Information

This section contains details about the TKS subsystem, which is one of the possible subsystems that can be installed as a web application in a Certificate Server instance.

Table 12.6. TKS Subsystem Information for the Default Instance (pki-tomcat)

Setting Value
Main directory /var/lib/pki/pki-tomcat/tks/
Configuration directory /var/lib/pki/pki-tomcat/tks/conf/[a]
Configuration file /var/lib/pki/pki-tomcat/tks/conf/CS.cfg
Subsystem certificates Transport certificate
Storage certificate
SSL server certificate
Audit log signing certificate
Subsystem certificate[b]
Security databases /var/lib/pki/pki-tomcat/alias/[c]
Log files /var/lib/pki/pki-tomcat/tks/logs/
Install log /var/log/pki/pki-tks-spawn-date.log
Uninstall log /var/log/pki/pki-tks-destroy-date.log
Audit logs /var/log/pki/pki-tomcat/tks/signedAudit/
Web services files Agent services: /var/lib/pki/pki-tomcat/tks/webapps/tks/agent/
Admin services: /var/lib/pki/pki-tomcat/tks/webapps/tks/admin/
[a] Linked to /etc/pki/pki-tomcat/tks/
[b] 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.
[c] Note that all subsystem certificates are stored in the instance security database

12.1.6. TPS Subsystem Information

This section contains details about the TPS subsystem, which is one of the possible subsystems that can be installed as a web application in a Certificate Server instance.

Table 12.7. TPS Subsystem Information for the Default Instance (pki-tomcat)

Setting Value
Main directory /var/lib/pki/pki-tomcat/tps/
Configuration directory /var/lib/pki/pki-tomcat/tps/conf/[a]
Configuration file /var/lib/pki/pki-tomcat/tps/conf/CS.cfg
Subsystem certificates Transport certificate
Storage certificate
SSL server certificate
Audit log signing certificate
Subsystem certificate[b]
Security databases /var/lib/pki/pki-tomcat/alias/[c]
Log files /var/lib/pki/pki-tomcat/tps/logs/
Install log /var/log/pki/pki-tps-spawn-date.log
Uninstall log /var/log/pki/pki-tps-destroy-date.log
Audit logs /var/log/pki/pki-tomcat/tps/signedAudit/
Web services files Agent services: /var/lib/pki/pki-tomcat/tps/webapps/tps/agent/
Admin services: /var/lib/pki/pki-tomcat/tps/webapps/tps/admin/
[a] Linked to /etc/pki/pki-tomcat/tps/
[b] 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.
[c] Note that all subsystem certificates are stored in the instance security database

12.1.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 12.8, “Subsystem File Locations”.

Table 12.8. Subsystem File Locations

Directory Location Contents
/var/lib/instance_name Contains the main instance directory, which is the location for user-specific directory locations and customized configuration files, profiles, certificate databases, web files, and other files for the subsystem instance.
/usr/share/java/pki Contains Java archive files shared by the Certificate System subsystems. 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)
Not used by the TPS subsystem.
/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.
/var/lib/tomcat5/common/lib Contains links to Java archive files shared by local Tomcat web applications and shared by the Certificate System subsystems. Not used by the TPS subsystem.
/var/lib/tomcat5/server/lib Contains links to Java archive files used by the local Tomcat web server and shared by the Certificate System subsystems. Not used by the TPS subsystem.
/usr/shared/pki Contains the Java archive files used by the Tomcat server and applications used by the Certificate System instances. Not used by the TPS subsystem.
/usr/lib/httpd/modules
/usr/lib64/httpd/modules
 Contains Apache modules used by the TPS subsystem. Not used by the CA, KRA, OCSP, or TKS subsystems.
/usr/lib/mozldap
/usr/lib64/mozldap
 Mozilla LDAP SDK tools used by the TPS subsystem. Not used by the CA, KRA, OCSP, or TKS subsystems.