Chapter 13. 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.

13.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.
A subsystem can be installed within a particular instance using the pkispawn command.

13.1.1. Instance-specific Information

For instance information for the default instance (pki-tomcat), see Table 2.2, “Tomcat Instance Information”

Table 13.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.

13.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 13.2. 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)
TLS server certificate
Audit log signing certificate
Subsystem certificate[b]
Security databases /var/lib/pki/pki-tomcat/alias/[c]
Log files /var/log/pki/pki-tomcat/ca/logs/[d]
Install log /var/log/pki/pki-ca-spawn.date.log
Uninstall 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/lib/pki/pki-tomcat/ca

13.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 13.3. 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
TLS 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

13.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 13.4. 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
TLS 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

13.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 13.5. Every time a subsystem is created either through the initial installation or creating additional instances with (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
TLS 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

13.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 13.6. 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
TLS 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

13.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 2.8, “Subsystem File Locations”.

Table 13.7. 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.